deepseek-web-retrieval 0.6.0 → 0.8.0

package/docs/agents/pi.md

@@ -22,6 +22,8 @@ When loaded, it adds:
 Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path. For
 shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
 
 ## Requirements
 
@@ -42,7 +44,9 @@ npx deepseek-web-retrieval init --host pi --scope <project|global> \
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing
-packages and MCP servers — and writes nothing until you pass `--apply`. The default path is
+packages and MCP servers — and writes nothing until you pass `--apply`. Add `--pin` to
+register the exact version of the CLI you are running instead of the always-latest
+package name. The default path is
 the extension: the plan appends `npm:deepseek-web-retrieval` to the `packages` array in
 `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project), and Pi resolves the
 source at the next session start (the first launch fetches the package from npm;
@@ -102,6 +106,12 @@ Fetch https://pi.dev/docs/latest/extensions and summarize the extension lifecycl
 The model calls `deepseek_web_search` or `deepseek_fetch` — the same names over both paths;
 only the MCP fallback prefixes them with `mcp__deepseek__`.
 
+The search tool accepts an optional `original_question` input — the user's question in their
+own words — forwarded as DeepSeek's `ori_question` to sharpen search intent. When the model
+leaves it blank, the extension falls back to the most recent user message in the session
+(best-effort; truncated to the API's 128-character limit). The MCP fallback path has no
+session access, so there a blank input simply omits the parameter.
+
 ## Configuration
 
 The runtime config surface is the same `DEEPSEEK_*` environment the MCP server reads
@@ -109,40 +119,53 @@ The runtime config surface is the same `DEEPSEEK_*` environment the MCP server r
 `deepseekWebRetrieval` settings namespace for the off switches (written by the installer;
 it outranks the environment and is preserved by Pi's own settings rewrites).
 
+The shared config file (`~/.config/deepseek-web-retrieval/config.json`, camelCase keys —
+on Windows, `%APPDATA%\deepseek-web-retrieval\config.json`)
+also sits in this surface, layered under the environment, and needs no forwarding on any
+path — the extension and the MCP server both read the file themselves. One file therefore
+configures every host running this package, with this host's environment and settings
+still outranking it. `npx deepseek-web-retrieval config` prints what actually resolves —
+each knob's value and source, with file warnings surfaced and `--search "<query>"` running
+one billed search through it all.
+
 ### Search
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
-| `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
-| `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
-| `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
-| `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |
-| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `1200` | Per-result summary cap, 0–1,000,000. |
-| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `30000` | Search timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
+The "Config file" column names each key's camelCase twin in the shared config file —
+one vocabulary pair, one pipeline. `—` marks host-integration entries the file rejects.
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_SEARCH` | — | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
+| `DEEPSEEK_SEARCH_COUNT` | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `maxResults` | `10` | Results returned to the model after filtering, 0–50; defaults to `DEEPSEEK_SEARCH_COUNT` when unset. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `minRerank` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
+| `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | `blockedDomains` | unset | Comma-separated; adds `-site:` operators to the query. |
+| `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | `includeDomains` | unset | Comma-separated; restricts results with `site:` operators. |
+| `DEEPSEEK_SEARCH_LANGUAGE` | `language` | unset | Adds a `lang:` operator, for example `zh,en`. |
+| `DEEPSEEK_SEARCH_LOCALIZATION` | `searchLocalization` | unset | Valid IPv4 or IPv6 address sent as DeepSeek's `localization` to prefer geo-localized results; invalid values are ignored. Deployment-level only, never a per-call parameter. |
+| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `maxSummaryChars` | `1200` | Per-result summary cap, 0–1,000,000. |
+| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `searchTimeoutMs` | `30000` | Search timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
 
 ### Fetch
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_ENABLE_FETCH` | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
-| `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. The only output cap on this path. |
-| `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
-| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset | If set, only these hosts and subdomains may be fetched. |
-| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
-| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. Set `false`/`0` to disable. |
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_FETCH` | — | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
+| `DEEPSEEK_FETCH_MAX_CHARS` | `fetchMaxChars` | `16000` | Maximum characters returned, including the title, 0–1,000,000. The only output cap on this path. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
+| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | `fetchAllowedDomains` | unset | If set, only these hosts and subdomains may be fetched. |
+| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | `fetchBlockedDomains` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
+| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `fetchBlockPrivateHosts` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. Set `false`/`0` to disable. |
 
 ### Credentials and retries
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_API_KEY` | required | DeepSeek API key, read from the Pi process environment. |
-| `DEEPSEEK_MAX_RETRIES` | `0` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
-| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_API_KEY` | — | required | DeepSeek API key, read from the Pi process environment. |
+| `DEEPSEEK_MAX_RETRIES` | `maxRetries` | `2` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
+| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `retryBaseDelayMs` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
 
 Invalid values fall back to the shared default.
 

package/docs/configuration.md

@@ -0,0 +1,109 @@
+# Configuration guide
+
+The one reference for how every knob resolves on every host: the layering
+chain, the shared config file, the full knob vocabulary, and which layer to set.
+Behavior (what search and fetch do) lives in the README's
+[General behavior](../README.md#general-behavior); per-host mechanics (output
+caps, deadlines, how the environment reaches a stdio server) live in the host
+guides: [Codex](agents/codex.md), [Claude Code](agents/claude-code.md),
+[Pi](agents/pi.md),
+[OpenCode](agents/opencode-v2.md).
+
+## The resolution chain
+
+Every knob resolves through one chain, low → high, identically on every host:
+
+```
+built-in defaults  <  shared config file  <  DEEPSEEK_* environment  <  host-native config
+```
+
+A higher layer always wins, so nothing already configured loses effect. The
+host-native layer means OpenCode's plugin options (`opencode.jsonc`), Pi's
+`deepseekWebRetrieval` settings namespace, and — for MCP hosts — the per-server
+`env` block in the host's registration (that block is how an environment
+variable arrives, not a fifth layer).
+
+## The shared config file
+
+`$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json` when `XDG_CONFIG_HOME` is
+set (this wins on every platform, Windows included); otherwise
+`~/.config/deepseek-web-retrieval/config.json` on Linux and macOS and
+`%APPDATA%\deepseek-web-retrieval\config.json` on Windows. camelCase keys:
+
+```json
+{
+  "count": 20,
+  "blockedDomains": ["pinterest.com"],
+  "language": "zh",
+  "searchLocalization": "203.0.113.7"
+}
+```
+
+Unknown keys and host-integration keys (below) draw a one-line stderr warning
+and are otherwise ignored — a bad file never blocks startup. The API key never
+goes in the file; it keeps its existing channels (`DEEPSEEK_API_KEY` in the
+environment, or OpenCode's stored credential).
+
+## Knob classes
+
+| Knob class | Shared file | Examples |
+| --- | --- | --- |
+| API behavior — the user↔DeepSeek relationship | yes — that is the point of the file | `count`, `blockedDomains`, `language`, `maxRetries` |
+| Host-sensitive — interacts with host output caps and deadlines | carries the safe defaults; a host layer is the recommended override point | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars` |
+| Host integration — the host's tool landscape | rejected — warned about and ignored | `searchEnabled`, `setDefaultWebsearch`, `apiKeySource` |
+
+Keep host-independent intent in the shared file; prefer a host layer when a
+host-sensitive knob would cross its host's cap or deadline.
+
+## The knob vocabulary
+
+One knob, two names: the camelCase key for the shared file and OpenCode's
+options, the `DEEPSEEK_*` variable for the environment. The table generates
+from the same config vocabulary the adapters resolve through, so it cannot
+drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
+
+<!-- generated: knob-table — edit src/core/config-summary.ts or env.ts, then run `bun run docs:matrix` -->
+
+| File / OpenCode key | Environment | Default |
+| --- | --- | --- |
+| `count` | `DEEPSEEK_SEARCH_COUNT` | 10 |
+| `maxResults` | `DEEPSEEK_SEARCH_MAX_RESULTS` | follows `count` (10) |
+| `minRerank` | `DEEPSEEK_SEARCH_MIN_RERANK` | 0 |
+| `minAuthority` | `DEEPSEEK_SEARCH_MIN_AUTHORITY` | 0 |
+| `allowUnknownAuthority` | `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | true |
+| `blockedDomains` | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset |
+| `includeDomains` | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset |
+| `language` | `DEEPSEEK_SEARCH_LANGUAGE` | unset |
+| `searchLocalization` | `DEEPSEEK_SEARCH_LOCALIZATION` | unset |
+| `maxSummaryChars` | `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | 1200 |
+| `searchTimeoutMs` | `DEEPSEEK_SEARCH_TIMEOUT_MS` | 30000 |
+| `fetchMaxChars` | `DEEPSEEK_FETCH_MAX_CHARS` | 16000 |
+| `fetchAllowedDomains` | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset |
+| `fetchBlockedDomains` | `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset |
+| `fetchTimeoutMs` | `DEEPSEEK_FETCH_TIMEOUT_MS` | 30000 |
+| `fetchBlockPrivateHosts` | `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | true |
+| `maxRetries` | `DEEPSEEK_MAX_RETRIES` | 2 |
+| `retryBaseDelayMs` | `DEEPSEEK_RETRY_BASE_DELAY_MS` | 250 |
+
+<!-- /generated: knob-table -->
+
+## Special semantics
+
+- **`maxResults` follows `count`** when left unset — configure only `count` and
+  the cap moves with it. An explicit `maxResults` still caps; `count` never
+  follows `maxResults`.
+- **Some switches are false-only.** `allowUnknownAuthority`,
+  `fetchBlockPrivateHosts`, `searchEnabled`, and `fetchEnabled` are on by
+  default; the environment can only turn them off (`false`, `0`, `no`, or
+  `off`). The last two have no file key — they are host-integration keys — so
+  they exist only as `DEEPSEEK_ENABLE_SEARCH` and `DEEPSEEK_ENABLE_FETCH`. A
+  value like `=true` changes nothing.
+- **Invalid environment values are dropped** at startup and the default
+  applies. `npx deepseek-web-retrieval config` reports every dropped or
+  unknown `DEEPSEEK_*` variable as a warning and exits 1, alongside file
+  problems.
+- **`searchLocalization` must be a valid IPv4 or IPv6 address**; anything else
+  is dropped at option resolution. It is deployment-level configuration, never
+  a per-call tool parameter.
+- **Domains** in the environment are comma-separated; entries that are not
+  domains are dropped (and reported by `config`).

package/docs/design/config-layering-design.md

@@ -0,0 +1,180 @@
+# Configuration layering design
+
+Design note for the shared configuration base layer across the three shipped adapters (MCP
+server, OpenCode plugin, Pi extension). It records the parameter taxonomy, the precedence
+model, and the per-adapter composition so the design survives between conversations. Host
+capability facts live in [control-matrix.md](../research/control-matrix.md); the config
+surface inventory was verified against the code on 2026-10-23.
+
+## Problem
+
+The state this design replaced — recorded here as history, not as the present. The option
+pipeline was already single-sourced (names, defaults, clamping in
+`src/core/constants.ts` → `src/core/env.ts` → `src/core/options.ts`), but the *channels*
+that fed it were fragmented per host, and a multi-host user configured the same intent in
+up to three ways:
+
+- **Pi** — extension runs in-process; `DEEPSEEK_*` shell variables just worked.
+- **Codex** — stdio children do not inherit the parent environment, and the installer's
+  `env_vars` entry forwarded **only** `DEEPSEEK_API_KEY`; every other knob set in the
+  shell never reached the server unless the user hand-edited `config.toml` to add each
+  variable name. (The entry now forwards every `DEEPSEEK_*` name — see the Codex
+  consequence in [ADR-0002](../adr/0002-shared-config-base-layer.md).)
+- **OpenCode** — the plugin resolved **only** `ctx.options` (opencode.json plugin
+  options, camelCase); `DEEPSEEK_*` variables configured nothing there, so the same
+  knob had a second, differently-named vocabulary. (The plugin now composes
+  file < environment < `ctx.options` — see the per-adapter composition below.)
+
+One intent ("20 results, block pinterest.com"), three configuration acts, two
+vocabularies, one silent-failure trap. The isolation was accidental, not chosen.
+
+## Parameter taxonomy
+
+Isolation versus unification is decided per class, not globally:
+
+| Class | Parameters | Policy |
+| --- | --- | --- |
+| **API behavior** — describes the user↔DeepSeek relationship, host-independent | `count`, `maxResults`, `minRerank`, `minAuthority`, `allowUnknownAuthority`, `blockedDomains`, `includeDomains`, `language`, `searchLocalization`, `maxRetries`, `retryBaseDelayMs` | Shared base; identical everywhere unless a host layer overrides |
+| **Host-sensitive** — interacts with host output caps / deadlines (OpenCode 2,000 lines / 50 KiB; Pi MCP 20 KB + 60 s; Pi extension uncapped; Claude Code 25k tokens) | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars` | Shared base gives the safe default; **per-host override in the host-native layer is the recommended place** to raise them |
+| **Host integration** — describes the host's tool landscape, not the API | `searchEnabled`, `fetchEnabled`, `setDefaultWebsearch`, `fetchOverrideWebfetch`, `fetchRegisterTool`, `apiKeySource` | **Deliberately isolated.** Installer-written, host-native config only; the shared file rejects them |
+
+Security-shaped knobs (`fetchAllowedDomains`, `fetchBlockedDomains`, `fetchBlockPrivateHosts`)
+are classed as API behavior: they are deployment policy about the DeepSeek call itself, and a
+shared base strengthens rather than weakens them (one policy instead of three drifting ones).
+
+## The layering model
+
+Precedence, low → high, identical semantics in every adapter:
+
+```
+built-in defaults  <  shared config file  <  DEEPSEEK_* environment  <  host-native config
+```
+
+- **Host-native config** means: OpenCode `ctx.options` (opencode.json plugin entry), Pi's
+  `deepseekWebRetrieval` settings namespace (the two switches), and — for MCP hosts — the
+  per-server `env` block in the host's MCP registration (that block is *how* an environment
+  variable arrives, not a fifth layer).
+- Host-native layers keep outranking the base: installer-written intent (capability tiers)
+  and explicit per-host overrides always win, so the blast radius of a bad shared value is
+  bounded by whatever the host layer pins.
+- The two vocabularies stay as they are — `DEEPSEEK_*` snake-case names for the environment,
+  camelCase `PluginOptions` keys for the file and OpenCode options — both generated from the
+  same single source and documented side by side.
+
+## The shared config file
+
+- **Path:** `$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json`, defaulting to
+  `~/.config/deepseek-web-retrieval/config.json`. On win32 an explicit, non-empty
+  `XDG_CONFIG_HOME` still wins; otherwise the conventional Roaming root applies —
+  `%APPDATA%\deepseek-web-retrieval\config.json`, falling back to
+  `<home>\AppData\Roaming\deepseek-web-retrieval\config.json` when `%APPDATA%` is
+  unset. User scope, one file. A project-scope file
+  is a confirmed non-goal for this iteration (open question below).
+- **Format:** JSON object; keys are the camelCase `PluginOptions` vocabulary (class 1 and 2
+  only). Example:
+
+  ```json
+  {
+    "count": 20,
+    "blockedDomains": ["pinterest.com"],
+    "language": "zh",
+    "searchLocalization": "203.0.113.7"
+  }
+  ```
+
+- **Validation:** the file's parsed object feeds the existing `resolvePluginOptions` —
+  clamps, IP validation, and domain normalization all come along for free. Unknown keys and
+  class-3 (host-integration) keys are **rejected with a one-line stderr warning** and
+  otherwise ignored; a missing or unparseable file contributes nothing (a warning line for
+  the unparseable case), mirroring the Pi settings reader's conventions.
+- **The API key is deliberately absent.** Auth keeps its existing channels
+  (`DEEPSEEK_API_KEY`, OpenCode's auth store, Pi's env) — a config file is liable to end up
+  synced through dotfiles, and widening key storage is a security-surface decision this
+  design does not make.
+
+## Per-adapter composition
+
+- **MCP server** (`src/mcp/serve.ts`): `resolveEnvOptions(env)` becomes
+  `resolveEnvOptions(env, readFileOptions())` — file keys under environment keys. The server
+  reads the file itself, so **the Codex `env_vars` trap disappears** regardless of what the
+  host forwards.
+- **Pi extension** (`src/pi/extension.ts`): `resolveExtensionOptions` inserts the file
+  between defaults and the environment; the settings namespace stays on top, unchanged.
+- **OpenCode plugin** (`src/opencode/plugin.ts`): `resolvePluginOptions(ctx.options)` becomes
+  `resolvePluginOptions({ ...fileOptions(), ...pluginOptionsFromEnv(process.env), ...ctx.options })`
+  — file, then environment, then the host layer. Additive only: existing opencode.json
+  options keep winning exactly as before; the change is that the file and environment now
+  work on this host too.
+
+## Installer changes
+
+- **Codex `env_vars`:** enumerate **every** `DEEPSEEK_*` name (generated from
+  `src/core/constants.ts`, the single source) instead of only `DEEPSEEK_API_KEY`, so
+  environment overrides work on Codex without hand-editing `config.toml`. The note the
+  installer prints is updated to match.
+- No other host artifacts change: the installer never writes the shared file (it is a user
+  authoring surface, like a shell profile), and capability tiers stay where they are.
+
+## Visibility
+
+A bad shared value now fails everywhere at once, so effective configuration must be visible:
+
+- The MCP server's startup stderr line (already printing the client identity and enabled
+  tools) additionally prints **deviations from defaults only** — e.g.
+  `config: count=20 blockedDomains=1 language=zh` — keeping the line short while showing
+  every non-default knob a multi-layer resolution produced.
+- The OpenCode plugin and Pi extension print the same deviation summary once, at
+  registration time, through their host's logging channel (implementer picks the least
+  noisy channel per host; the content contract is "non-default effective values").
+- `deepseek-web-retrieval config` is the user-facing arm: it prints every knob with its
+  value and source, replays the file's warnings where a human actually looks, and its
+  `--search` variant verifies the whole chain (key, config, network) with one billed
+  request.
+
+## What this design does not change
+
+- `need_content` stays hardcoded `false` ([search-inline-content.md](../research/search-inline-content.md)).
+- `ori_question` remains per-call-only (`original_question` input / Pi session fallback); it
+  is not configurable.
+- Auth surfaces, capability tiers, and the installer's plan/confirm flow.
+
+## Testing
+
+- Unit: file reader (missing / unparseable / unknown-key / class-3-key rejection with
+  warning), precedence matrix per adapter (defaults < file < env < host) asserted through
+  each adapter's existing resolution entry points.
+- The installer's Codex plan snapshot gains the full `env_vars` list.
+- Existing suites stay green; e2e scenarios unaffected (the file is absent in CI, which is
+  itself the empty-layer case).
+
+## Rollout
+
+Additive and non-breaking: no existing configuration loses effect, no precedence between
+existing layers changes. Documentation updates ship with the code: README gains a
+"Configuration" section with the precedence table and the two-vocabulary table; the host
+guides' option tables gain a shared-file column; the control-matrix note's Pi sentence
+("There is no per-extension options channel: the runtime config surface is the
+`DEEPSEEK_*` environment") is updated to name the file as part of that surface.
+
+**Amendment, 2026-10-23** — two changes approved after this design was confirmed alter
+the effective behavior of *untouched* configurations, superseding the "no existing
+configuration loses effect" sentence for those two knobs:
+
+1. `maxResults` now follows the effective `count` when unset, so `count`-only
+   configurations return `count` results instead of silently truncating to the old
+   default of 10 (the one-directional asymmetry is documented at the resolution site in
+   `src/core/options.ts`).
+2. Transient failures (408/425/429/5xx) retry twice by default instead of zero
+   (rationale and the dated vendor-survey correction live in
+   `docs/research/search-api-defaults.md`).
+
+## Decisions (confirmed 2026-10-23)
+
+1. **Project-scope file:** not in this iteration — hosts already own project-scope
+   semantics, and the extra precedence row is not yet earned by demand.
+2. **Invalid-key warnings:** one stderr line per bad key at first resolution — the noise
+   buys typo detection (`"retries"` vs `"maxRetries"`) in a hand-edited file.
+3. **File naming:** `config.json` inside the `~/.config/deepseek-web-retrieval/`
+   directory (win32: `%APPDATA%\deepseek-web-retrieval\`) — room for future siblings.
+4. **ADR:** the layering decision is recorded as
+   [ADR 0002](../adr/0002-shared-config-base-layer.md) alongside this design note.

package/docs/design/installer-design.md

@@ -1,13 +1,13 @@
 # Installer design
 
 Design note for the install-time flow, shipped as the `deepseek-web-retrieval init`,
-`uninstall`, and `list` subcommands for **OpenCode, Pi, and Codex**. It records how the
-[control tiers](../research/control-matrix.md) map to the artifacts the installer emits, so
-the design survives between conversations. Research backing lives in
+`uninstall`, and `list` subcommands for **OpenCode, Pi, Codex, and Claude Code**. It records how the
+[control tiers](../research/control-matrix.md) map to the artifacts the installer emits, so the design
+survives between conversations. Research backing lives in
 [control-matrix.md](../research/control-matrix.md); host facts in [hosts.jsonc](../hosts.jsonc).
 Remaining hosts get host modules here as their guides ship.
 Examples involving other hosts describe design requirements for future modules;
-the current CLI accepts only the three shipped hosts above.
+the current CLI accepts only the four shipped hosts above.
 
 ## Principles
 
@@ -44,9 +44,9 @@ already exists, and the installer uses three phases:
    Report the conflict surface: existing rules steering toward another web tool; other
    web-capable MCP servers already on the field; array-valued keys the plan must merge
    into rather than replace (`disabledTools`, `permissions.deny`, permissions
-   `exclude`, `disabled_tools`); and higher layers (Claude Code managed policy, Devin
-   enterprise team settings) that would outrank what the
-   installer writes.
+   `exclude`, `disabled_tools`); and higher layers (Claude Code managed policy — its
+   existence is checked by the claude-code module; Devin enterprise team settings) that
+   would outrank what the installer writes.
 2. **Merge or snapshot.** Array keys merge with existing entries, recording exactly
    which entries the installer appended; single-value keys (`websearch.provider`, Pi's
    `exposure`) snapshot the prior value before overwriting; files the installer creates
@@ -71,7 +71,9 @@ already exists, and the installer uses three phases:
   competitor, not third-party web MCP servers — those must be excluded too (the
   per-host keys cover them), or routing is not actually forced. Concretely: Pi's
   per-server `enabled` key lets the plan disable detected web-capable competitors
-  (each prior value snapshotted for uninstall); Codex has no per-server kill switch,
+  (each prior value snapshotted for uninstall); Claude Code excludes them the same way
+  via server-level `mcp__<server>` deny rules appended to `permissions.deny`; Codex has
+  no per-server kill switch,
   so a detected web-capable competitor makes the plan refuse the tier instead of
   promising non-exclusive routing; OpenCode's forced is replacement, which no
   third-party server overrides. Detection classifies a server web-capable from its
@@ -156,9 +158,9 @@ the artifacts below name the path where they differ.
 | Optional | Host config registering the integration: Pi's extension path appends an `npm:<package>` source to `packages` in settings.json; the MCP paths register the server (Pi's MCP entry needs `"exposure": "direct"`; the extension path needs nothing — extension tools are `direct` by Pi's own default) |
 | Preferred | The above plus a rules file for the host (file names per host in the [per-host reference](../research/control-matrix.md#per-host-reference)); the rules name the path's tool ids (`deepseek_web_search` for the extension, `mcp__deepseek__deepseek_web_search` for MCP) |
 | Forced (replacement) | OpenCode plugin options (`setDefaultWebsearch` / `fetchOverrideWebfetch`) |
-| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Codex, lacking a per-server kill switch, refuses the tier instead; Pi's extension path additionally refuses when a web-capable `packages`/`extensions` source is listed in settings.json (no per-package kill switch exists) |
+| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Claude Code appends server-level `mcp__<server>` deny rules to `permissions.deny` (merging with the user's own entries); Codex, lacking a per-server kill switch, refuses the tier instead; Pi's extension path additionally refuses when a web-capable `packages`/`extensions` source is listed in settings.json (no per-package kill switch exists) |
 | Forced (de-facto) | Nothing beyond the Optional artifacts — no competitor exists |
-| Off | Codex writes the capability's raw tool name into the server entry's `disabled_tools` (host-native: the tool leaves the model's context; the user's own entries in that array are kept); the other MCP entry writes the capability's false-only server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); Pi's extension path writes the same switches into the `deepseekWebRetrieval` settings namespace the extension reads at load; both capabilities off refuses to install |
+| Off | Codex writes the capability's raw tool name into the server entry's `disabled_tools` (host-native: the tool leaves the model's context; the user's own entries in that array are kept); Claude Code appends the capability's full tool id (`mcp__deepseek__*`) to `permissions.deny`, the same host-native removal; the other MCP entry writes the capability's false-only server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); Pi's extension path writes the same switches into the `deepseekWebRetrieval` settings namespace the extension reads at load; both capabilities off refuses to install |
 
 OpenCode additionally appends `permissions` allow entries for exactly the tools it
 registers (`websearch`, `deepseek_fetch`, and `webfetch` when fetch is forced), merged
@@ -194,10 +196,19 @@ into any existing `permissions` array rather than replacing it.
   reverts cannot re-enable a still-excluded competitor.
 - Verify is file-level: after apply it re-reads each written file and asserts every op
   holds (set values in place, appended entries present, rules block present). Higher
-  layers would be a plan-time detect concern, and none of the three shipped hosts
-  documents a layer above user config, so there is nothing to check there yet.
+  layers are a plan-time detect concern; Claude Code documents one (managed policy), and
+  the claude-code module reports an existing managed-settings.json instead of failing
+  silently. The other shipped hosts document no layer above user config.
 - Only a bare `--apply` enables writes; assigning a value such as `--apply=false`
   is a usage error and writes nothing.
+- `--pin` is opt-in version pinning: the ref written into host config gets the
+  running CLI's version appended (`name` becomes `name@<version>`; a ref already
+  ending in a version keeps it), so a host resolves that exact release instead of
+  the latest publish. Without the flag the ref stays unpinned, byte-identical to
+  before; re-running `init --pin` from a newer CLI moves the pin. Ref identity —
+  orphan, upgrade, and unexcludable-competitor detection — compares package names
+  with the `@version` suffix stripped (`samePackageName` in ownership.ts), so a
+  pinned ref still matches the lineage an earlier init registered.
 - File verification precedes the install-record commit. A write or verification
   failure restores the pre-apply files and record and checks the restored values.
   `ApplyError.status` is `rolled_back` only after recovery and new-claim cleanup
@@ -216,7 +227,7 @@ host-side tool filtering.
 
 ## Hosts without an installer story
 
-Claude Code, Cursor, Devin, GitHub Copilot, and Cline still have no
+Cursor, Devin, GitHub Copilot, and Cline still have no
 host module; their artifacts (from the tier-to-artifact mapping) remain hand-edited
 config until a module lands here. OpenCode's `opencode plugin add` remains available but
 cannot pass options or manage snapshots; `init` supersedes it for tiered installs.

package/docs/hosts.jsonc

@@ -102,11 +102,15 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet",
+      "status": "supported",
       "control": {
         "search": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebSearch\"]` removes the tool from context" },
         "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebFetch\"]`, or `CLAUDE_CODE_DISABLE_WEB_FETCH=1`" }
       },
+      "adapter": "src/mcp",
+      "installer": "src/installer/hosts/claude-code",
+      "guide": "docs/agents/claude-code.md",
+      "e2eScenario": "claude-code"
     },
     {
       "name": "cursor",

package/docs/integration.md

@@ -17,7 +17,7 @@ ship built-in web tools. MCP tools can add equivalent tools, but do not replace
 | Native tool / fetch override | No | Yes | Host tool API | OpenCode v2 adapter |
 | Custom tool plugin | Yes | Yes | Host plugin API | Cline CLI/SDK; no adapter yet |
 | Extension API | Yes | Yes | Host extension API | Pi adapter (`src/pi/`) |
-| MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi and Codex guides) |
+| MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi, Codex, and Claude Code guides) |
 | CLI/HTTP wrapper | Yes | Yes | Host can call external tools | Not shipped |
 
 MCP is a protocol, not an agent. It is one possible transport for hosts that support MCP
@@ -35,7 +35,7 @@ Rows are sorted with open-source hosts first, then by host name alphabetically.
 | Codex | 0.163.0 | Yes (Apache-2.0) | No | No | MCP server | Supported |
 | OpenCode | 2.0.32 | Yes (MIT) | Yes | Yes | native websearch provider or native tool/fetch override | Supported |
 | Pi | 1.3.0 | Yes (MIT) | No | No | extension API or MCP server | Supported |
-| Claude Code | 2.1.303 | No | No | No | MCP server | No adapter yet |
+| Claude Code | 2.1.303 | No | No | No | MCP server | Supported |
 | Cursor | 2026.10.08 | No | No | No | MCP server | No adapter yet |
 | Devin | 3000.11.92 | No | No | No | MCP server | No adapter yet |
 | GitHub Copilot | 1.0.98 | No | No | No | MCP server | No adapter yet |
@@ -48,7 +48,7 @@ Codex are Apache-2.0; OpenCode and Pi are MIT. Claude Code and
 Cursor are proprietary. GitHub Copilot CLI and Devin CLI publish installers and docs, not
 source code, under proprietary terms.
 
-OpenCode, Pi, and Codex have supported setup guides and installer host modules. The
+OpenCode, Pi, Codex, and Claude Code have supported setup guides and installer host modules. The
 MCP server in `src/mcp/` provides a possible stdio path for the remaining hosts, but
 protocol compatibility alone does not establish a tested host setup. For those rows,
 `No adapter yet` means no supported host-specific adapter or setup guide is shipped.
@@ -66,8 +66,10 @@ the details: built-in web tools and their kill switches, MCP registration, and r
 - **OpenCode v2** — Uses OpenCode's native plugin API and
   exposes both a websearch provider and a fetch tool/override. See
   [OpenCode v2](agents/opencode-v2.md).
-- **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. See
-  [Claude Code](research/control-matrix.md#claude-code).
+- **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. Supported through
+  the MCP server; see
+  [Claude Code](agents/claude-code.md) and
+  [Claude Code in the per-host reference](research/control-matrix.md#claude-code).
 - **Codex** — Ships a built-in `web_search` tool. Supported through the MCP server; see
   [Codex](agents/codex.md) and [Codex in the per-host reference](research/control-matrix.md#codex).
 - **Cursor** — Uses the same `mcp.json` servers as the editor; ships built-in web search
@@ -94,9 +96,12 @@ For an installation managed by `init`:
    needed for uninstall. A global install can still claim shared configuration from a
    particular project, so keep the original working directory for upgrades.
 3. Refresh the package in the host and start or reload a session as described in its
-   guide. For Pi's extension path, use `pi update --extensions`. If you pin the host's
-   package version, pass the desired `--package deepseek-web-retrieval@X.Y.Z` to init;
-   updating the CLI alone does not update an independently pinned host package.
+   guide. For Pi's extension path, use `pi update --extensions`. To pin the host's
+   package to the exact version being run, pass `--pin` to init (it writes
+   `deepseek-web-retrieval@X.Y.Z` into the registration); upgrading a pinned install
+   means re-running init with the newer CLI, since updating the CLI alone does not
+   move an independently pinned host package. `--package` still overrides the ref
+   entirely.
 
 When upgrading from 0.4.0, Pi's default changes from MCP to the native extension.
 Pass `--path mcp` explicitly to retain MCP, or `--path extension` to migrate; the plan
@@ -116,7 +121,8 @@ Code importing the core's removed `formatFetchContent` helper must migrate to
 ## Available paths and future hosts
 
 - **MCP server** — shipped in `src/mcp/` (the fallback path in the [Pi](agents/pi.md) guide
-  and the path in the [Codex](agents/codex.md) guide); the broadest route for hosts that
+  and the path in the [Codex](agents/codex.md) and
+  [Claude Code](agents/claude-code.md) guides); the broadest route for hosts that
   support MCP tools. Protocol compatibility across these hosts is researched in
   [mcp-compatibility.md](research/mcp-compatibility.md).
 - **Native extension adapters** — the Pi extension adapter ships in `src/pi/`; a host whose