deepseek-web-retrieval 0.8.0 → 0.10.0

package/docs/design/installer-design.md

@@ -43,8 +43,9 @@ already exists, and the installer uses three phases:
 1. **Detect.** Read the host config, the rules files, and the registered MCP servers.
    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 — its
+   into rather than replace (Cline's `disabledTools`, Claude Code's `permissions.deny`,
+   permissions `exclude` arrays, Codex's and Devin's `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
@@ -69,22 +70,24 @@ already exists, and the installer uses three phases:
   conditions; it does not resolve them.
 - **Forced is conditional**: the exclusion kill switches remove the built-in
   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); 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
-  name plus its command/args/url — a heuristic the plan notes never hide. Forced also
-  overrides
-  explicit user choices (OpenCode's `websearch.provider`), and its deny rules affect
-  workflows beyond this project (a Claude Code deny cannot be carved out by allow
-  rules), so the plan must state the blast radius before the user approves it.
+  per-host keys cover them), or routing is not actually forced.
+  - Per-host exclusion of detected web-capable MCP servers: Pi's per-server
+    `enabled` key lets the plan disable them (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 name plus its
+    command/args/url — a heuristic the plan always discloses.
+  - Blast radius: forced also overrides explicit user choices (OpenCode's
+    `websearch.provider`), and its deny rules affect workflows beyond this
+    project (a Claude Code deny cannot be carved out by allow rules), so the plan
+    must state the blast radius before the user approves it.
 - **Forced is not universally available**: where hosts.jsonc records `forced: "none"`
   (Cursor's search today), the wizard does not offer the tier — the tier-level analogue
-  of the scope rule: honor or report, never offer what cannot be delivered. Some kill
+  of the scope rule below (honor or report, never silently downgrade: never offer what
+  cannot be delivered). Some kill
   switches are session-scoped (Copilot fetch's `--deny-tool`/`--excluded-tools` flags);
   an installer cannot persist them, so the plan reports that the exclusion evaporates on
   restart and offers what persistence exists.
@@ -158,9 +161,33 @@ 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`; 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 (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus exclusion of any other web-capable MCP servers the detect phase found — host by host below |
 | 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); 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 |
+| Off | A host-native removal of the capability's tool — host by host below |
+
+Forced (exclusion), host by host:
+
+- **Pi** sets each detected web-capable server's `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).
+
+Off, host by host:
+
+- **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 remaining MCP entry** (Pi's fallback) 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
@@ -186,10 +213,10 @@ into any existing `permissions` array rather than replacing it.
   comments and formatting in `opencode.jsonc` and Pi's `mcp.json` survive apply and
   uninstall; TOML edits go through `smol-toml` and drop comments, which the plan reports
   as a note. The hand-written JSONC stripper that predated this lived in `scripts/jsonc.ts`.
-- Install state lives per host and scope (global under
-  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); it
-  records snapshots, appended entries, created files, and created path prefixes — never
-  full file contents, so other servers' secrets stay out of the state file.
+- Install records live per host and scope (global under
+  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); they
+  record snapshots, appended entries, created files, and created path prefixes — never
+  full file contents, so other servers' secrets stay out of the install record.
 - Re-applying over a previous init inherits the original snapshots instead of recording
   the installer's own output as the "previous" value. Pi forced re-inits keep their
   competitor-disable ops even when those servers are already disabled, so orphan
@@ -256,8 +283,13 @@ edits append arrays. Preview generation is read-only and does not reserve locks.
 
 Operation locks are directories ending in `.deepseek-web-retrieval.lock`, with
 owner PID and start time inside. Ordinary success or failure releases them. A
-killed process may leave a lock: after confirming no installer is running, inspect
-config, install record, and persistent ownership claims, restore any inconsistent
-state, then remove the reported lock directory and generate a new plan. Locks are
+killed process may leave a lock; to recover from one:
+
+1. Confirm no installer is currently running.
+2. Inspect the config, install record, and persistent ownership claims.
+3. Restore any inconsistent state.
+4. Remove the reported lock directory and generate a new plan.
+
+Locks are
 never stolen based only on age or PID. Persistent `.owner.json` claims remain a
 separate safeguard against two installations owning one shared config.

package/docs/design/search-content-design.md

@@ -0,0 +1,133 @@
+# Search content design
+
+Design note for `need_content` — DeepSeek's inline-content search flag — across the two
+model-facing adapters (the MCP server and the Pi extension). It records the parameter
+split (who decides what), the envelope arithmetic that sets the defaults, the rendering
+contract, and the per-adapter composition, so the design survives between conversations.
+The facts it builds on are in [search-inline-content.md](../research/search-inline-content.md)
+(baseline 2026-10-23); the decision record is
+[ADR-0003](../adr/0003-need-content-per-call-boolean.md). This note was verified against
+the code on 2026-10-24.
+
+## Problem
+
+The wire parameter is a boolean the repo hardcoded `false`: search results carried a
+summary digest (`summary` falling back to `snippet`) and never a page body. An agent
+needing bodies had to guess which URLs to fetch from the digests — a wrong guess is a
+silent miss. Turning the flag on naively is not safe either: DeepSeek documents **no**
+size bound for the returned `content`, host output caps run as tight as Pi's 20 KB
+MCP-path truncation (middle truncation — whole results vanish), and the 30 s default
+search timeout does not budget for the server-side page crawl the flag triggers.
+
+## The parameter split
+
+Two axes, two owners:
+
+- **The agent owns the boolean.** `need_content` is a per-call, optional tool parameter
+  on every surface where this package defines the search tool's inputs (the MCP server
+  and the Pi extension), defaulting to `false`. It rides `SearchRequest.needContent`
+  (the `oriQuestion` pattern), not the resolved options — it changes nothing in option
+  state, only what that one call sends. Task type is the biggest determinant of whether
+  content helps, and only the model knows the task; the repo's other per-call parameters
+  (`count`, fetch `maxChars`) are the precedent: always exposed, never mode-gated.
+- **The deployment owns the envelope.** Two deployment-level knobs — never tool
+  parameters — apply whenever content flows: `searchContentMaxChars` (per-result body
+  budget) and `searchContentTimeoutMs` (the timeout a content call runs on, replacing
+  `searchTimeoutMs` for that call; the per-call `timeoutMs` cap still wins if shorter).
+  The model cannot see which host caps its output, so it cannot own a budget.
+
+## The envelope
+
+Defaults from the host-cap arithmetic in the research note:
+
+- `searchContentMaxChars` defaults to **1,500**. At the default `count=10`, bodies plus
+  the ~1k chars of per-result metadata land near 16 KB — under the tightest published
+  cap (Pi's 20 KB MCP-path truncation) for Latin-script pages. CJK-heavy responses
+  measure 3 bytes per character toward that cap, so a CJK-focused deployment on a
+  20 KB host should lower the budget or the count (at 1,500 chars/result, count ≈ 13 is
+  the 20 KB ceiling even for Latin text). The native Pi extension bypasses the MCP
+  layer entirely — neither its 20 KB truncation nor its 60 s timeout applies — so that
+  deployment can afford a larger budget.
+- `searchContentTimeoutMs` defaults to **60,000** — between the 30 s search default the
+  digest path keeps and the 300 s ceiling Codex allows, because the API must fetch
+  every result page server-side before responding and documents no latency statement.
+
+The total a response can carry is budget × count plus metadata. That product is the
+deployment's arithmetic to run when tuning either knob; the core does not narrow any
+parameter's range at runtime (see Decisions).
+
+## Per-adapter composition
+
+- **MCP server**: `need_content` in the zod input schema, forwarded as
+  `needContent: need_content === true`.
+- **Pi extension**: the same parameter in the TypeBox schema (`SEARCH_PARAMETERS` stays
+  a module-level constant on both surfaces — the schema is unconditional), forwarded the
+  same way.
+- **OpenCode**: no change. The host fixes the `websearch` provider input to `query`
+  (the upstream gap that already blocks per-call `count`), so the provider stays
+  summary-only; the envelope knobs resolve through the shared pipeline and are dormant
+  there. Documented next to the count gap in
+  [opencode-v2.md](../agents/opencode-v2.md).
+- **Installer**: no artifacts change. The knob defaults are global and the deviation
+  lines on every adapter already report non-default values through the config
+  vocabulary.
+
+## Processing and rendering
+
+`processResults` is mode-agnostic: a present, non-empty `content` **replaces** the
+digest (the summary is a proxy for the body it compresses), clamped to
+`searchContentMaxChars` with an ellipsis marker when shortened; an empty, whitespace,
+or missing body — the API documents per-result absence, and `need_content: false`
+responses carry an empty string — falls back to the digest path. `searchContentMaxChars:
+0` treats the body as absent. Each result carries `contentKind: "page" | "digest"` so
+the renderer knows the source: page bodies render as Markdown indented into the list
+item (heading and list structure survive); digests stay compacted to one line, as
+summaries always were. The `structuredContent` mirror carries the same `content`
+string on hosts that read it.
+
+## What this design does not change
+
+- Billing behavior: Search bills per successful request; `need_content` is not a price
+  modifier, so a content call costs the same as a digest call (and can replace fetch
+  calls at the same per-request price).
+- The fetch tool, its `maxChars` parameter, and the two-tool architecture — a content
+  call replaces *some* fetches, not the deep-read path.
+- `maxSummaryChars`, thresholds, dedup, query composition, and degradation.
+- `MAX_RESPONSE_BYTES` (5 MiB) — still the outer guard, still erroring rather than
+  truncating; the per-result budget keeps responses far below it.
+
+## Testing
+
+Wire assertions on both model-facing adapters (`need_content: true` reaching the wire;
+`false` by default), client tests for the flag and the timeout selection
+(`contentTimeoutMs` used only when the call asks for content), `processResults` tests
+for the body-over-digest precedence, the budget clamp and marker, the empty-body
+fallback, and the zero-budget drop, and format tests for the two rendering shapes.
+
+## Rollout
+
+Shipped behind default-`false` behavior: with no configuration and no parameter use,
+every surface behaves exactly as before (the wire still says `need_content: false`).
+Deployments opt in per call by the model, per host by the two envelope knobs. No
+installer or shared-file migration; the knobs join the config vocabulary and the
+generated knob table.
+
+## Decisions (confirmed 2026-10-24)
+
+1. The boolean is a per-call tool parameter, always exposed on the MCP server and the
+   Pi extension; no config mode gates it.
+2. The envelope is deployment-only: `searchContentMaxChars` (1,500) and
+   `searchContentTimeoutMs` (60,000), never tool parameters.
+3. A page body replaces the digest; empty bodies fall back to it.
+4. `need_content` does not control other parameters — neither their availability nor
+   their value ranges. Effects may be conditional (the envelope knobs apply only when
+   content flows); domains are static. No surveyed vendor couples a content flag to
+   another parameter's range ([search-inline-content.md](../research/search-inline-content.md)),
+   and a silent runtime narrowing (say, of `count`) would be a decision the model
+   cannot see. The budget × count arithmetic is the deployment's to run.
+5. OpenCode stays summary-only until the upstream provider input widens.
+6. The descriptions state facts — mechanics, latency, price, magnitude, the fetch
+   alternative — and no usage policy. When content is worth it is the model's per-call
+   judgment (or a user's rules file per deployment), not the tool author's; if usage
+   data later shows the parameter systematically ignored or overused, that is the point
+   to add minimal steering, decided by evidence.

package/docs/integration.md

@@ -7,7 +7,8 @@ use it depends on that agent's extension points.
 CLI/terminal agents only; IDE and editor extension surfaces are out of scope. Versions are
 the latest stable CLI release checked at that baseline unless noted otherwise. `No` means no
 documented native provider or override was found in the checked version; several hosts still
-ship built-in web tools. MCP tools can add equivalent tools, but do not replace built-ins.
+ship built-in web tools. MCP (Model Context Protocol) tools can add equivalent tools, but
+do not replace built-ins.
 
 ## Mechanisms
 
@@ -20,8 +21,12 @@ ship built-in web tools. MCP tools can add equivalent tools, but do not replace
 | 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
-tools. `Custom tool plugin` means adding tools; it does not replace a host's built-in tools.
+Why the mechanism distinction matters: some agents expose a native websearch provider,
+some only let you add tools, and some only support MCP. A "yes" for one mechanism does
+not mean the others are supported — the adapter code and docs need to match the
+mechanism the host actually provides. MCP is a protocol, not an agent: one possible
+transport for hosts that support MCP tools, never a host itself. `Custom tool plugin`
+means adding tools; it does not replace a host's built-ins.
 
 ## Host support
 
@@ -96,12 +101,13 @@ 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`. 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.
+   guide (for Pi's extension path, `pi update --extensions`).
+
+Two init flags change what gets registered. `--pin` pins the host's package to the exact
+version being run (`deepseek-web-retrieval@X.Y.Z` in the registration); upgrading a
+pinned install therefore means re-running init with the newer CLI, since updating the
+CLI alone does not move an independently pinned host package. `--package` 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
@@ -109,12 +115,15 @@ shows the old path's removals and retains the original uninstall snapshots. Open
 native plugin and Codex's MCP path remain the same. Standalone MCP installs no longer
 require OpenCode or Pi SDKs; native adapters use the SDKs provided by their hosts.
 
-Keep install records and ownership sidecars: deleting them loses recovery information
+Keep install records and ownership sidecars (the `.owner.json` claim files the installer
+writes beside shared config files): deleting them loses recovery information
 and can cause a later init to refuse an existing registration. If an operation was
 interrupted, follow the [recovery guidance](design/installer-design.md#persistence-and-concurrent-operations)
 before retrying. For manual installations, update the package reference or checkout and
 follow the host guide rather than adopting the config through init.
 
+### Breaking changes for library consumers
+
 Code importing the core's removed `formatFetchContent` helper must migrate to
 `formatFetchedContent`, which returns both `content` and `truncated`.
 
@@ -178,12 +187,6 @@ the README Usage section only after the adapter ships. To request evaluation for
 host, [open an issue](https://github.com/gwokhou/deepseek-web-retrieval/issues) with links
 to its plugin, tool, or MCP documentation.
 
-## Why the distinction matters
-
-Some agents expose a native websearch provider, some only let you add tools, and some only
-support MCP. A "yes" for one mechanism does not mean the others are supported. The adapter
-code and docs need to match the mechanism the host actually provides.
-
 ## Adding an adapter
 
 - Register the host and its version lock in [hosts.jsonc](hosts.jsonc), then regenerate

package/docs/research/control-matrix.md

@@ -113,30 +113,31 @@ scopes; keys locked to a single scope are enumerated in the
   `web_search = "disabled"` in `~/.codex/config.toml`. Trap: the `[tools] web_search =
   <bool>` form parses but discards the value at 0.163.0 — a silent no-op
   ([config source at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/config_toml.rs)).
-- **MCP registration** — `~/.codex/config.toml` `[mcp_servers.<name>]`: stdio
-  `command`/`args`/`env`/`env_vars`; `startup_timeout_sec` (30 s) and `tool_timeout_sec`
-  (300 s) defaults — the `DEFAULT_STARTUP_TIMEOUT`/`DEFAULT_TOOL_TIMEOUT` constants
-  ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs));
-  `enabled_tools`/`disabled_tools` (verbatim raw tool-name match, filtered before
-  registration so the model never sees a disabled tool; an empty `enabled_tools` allow-list
-  exposes nothing), per-tool approval modes, and output limits: MCP tool output can be
-  capped per tool via `output_token_limit` ("Token budget for one MCP tool's output,
-  before the standard 20% serialization allowance"; the default cap is not published
-  there)
-  ([mcp_types.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs)).
-  stdio children do not inherit the parent environment (only `HOME`, `PATH`, and explicit
-  `env`), so `DEEPSEEK_API_KEY` must be passed explicitly. When a tool result has
-  `structuredContent`, Codex replaces the content blocks with the serialized JSON. No SSE.
-  Codex identifies itself in the initialize handshake as clientInfo name `codex-mcp-client`
-  with title `Codex`
-  ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs)).
-  The official docs moved to learn.chatgpt.com
-  ([MCP](https://learn.chatgpt.com/docs/extend/mcp),
-  [config reference](https://learn.chatgpt.com/docs/config-file/config-reference); the old
-  developers.openai.com URLs 308-redirect there) and now document every key above — but
-  state 10 s/60 s timeout defaults, which describe an older release line; the 30 s/300 s
-  constants above are the facts at the locked 0.163.0 (docs discrepancy re-verified
-  2026-10-21).
+- **MCP registration** — `~/.codex/config.toml` `[mcp_servers.<name>]`:
+  - **Entry keys:** stdio `command`/`args`/`env`/`env_vars`; per-tool approval modes.
+  - **Timeouts:** `startup_timeout_sec` (30 s) and `tool_timeout_sec` (300 s) defaults —
+    the `DEFAULT_STARTUP_TIMEOUT`/`DEFAULT_TOOL_TIMEOUT` constants
+    ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs)).
+  - **Tool filtering:** `enabled_tools`/`disabled_tools` — verbatim raw tool-name match,
+    filtered before registration so the model never sees a disabled tool; an empty
+    `enabled_tools` allow-list exposes nothing.
+  - **Output limits:** MCP tool output can be capped per tool via `output_token_limit`
+    ("Token budget for one MCP tool's output, before the standard 20% serialization
+    allowance"; the default cap is not published there)
+    ([mcp_types.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs)).
+  - **Environment:** stdio children do not inherit the parent environment (only `HOME`,
+    `PATH`, and explicit `env`), so `DEEPSEEK_API_KEY` must be passed explicitly.
+  - **Result shape and identity:** when a tool result has `structuredContent`, Codex
+    replaces the content blocks with the serialized JSON. No SSE. Codex identifies itself
+    in the initialize handshake as clientInfo name `codex-mcp-client` with title `Codex`
+    ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs)).
+  - **Docs drift:** the official docs moved to learn.chatgpt.com
+    ([MCP](https://learn.chatgpt.com/docs/extend/mcp),
+    [config reference](https://learn.chatgpt.com/docs/config-file/config-reference); the
+    old developers.openai.com URLs 308-redirect there) and now document every key above —
+    but state 10 s/60 s timeout defaults, which describe an older release line; the
+    30 s/300 s constants above are the facts at the locked 0.163.0 (docs discrepancy
+    re-verified 2026-10-21).
 - **Rules** — `~/.codex/AGENTS.md` (with `AGENTS.override.md` preferred) at user scope;
   every `AGENTS.md` from the project root down to the cwd, concatenated root→cwd.
   Extensible via `project_doc_fallback_filenames` and `developer_instructions`
@@ -184,8 +185,10 @@ scopes; keys locked to a single scope are enumerated in the
   channel: the runtime config surface is the `DEEPSEEK_*` environment (the same pipeline as
   the MCP server), the shared config file
   (`~/.config/deepseek-web-retrieval/config.json`, layered under the environment), plus a
-  `deepseekWebRetrieval` settings namespace the installer writes for
-  the off tier — Pi preserves unknown settings keys on read and on its own rewrites
+  `deepseekWebRetrieval` settings namespace the installer writes for the `off` tier (a
+  capability switched off — the [tier-to-artifact
+  mapping](../design/installer-design.md#tier-to-artifact-mapping) defines it) — Pi
+  preserves unknown settings keys on read and on its own rewrites
   (`pi install`), verified at 1.3.0. Action methods such as `getSettings()` cannot be
   called during extension loading, so the adapter reads the settings files itself.
 - **MCP registration** — `~/.pi/agent/mcp.json` or `.pi/mcp.json`: stdio
@@ -320,11 +323,13 @@ scopes; keys locked to a single scope are enumerated in the
   `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.
+- **Claude Code forward-compat anchors (checked at the 2.1.303 lock)** — three facts a
+  baseline bump should re-verify against the then-current docs:
+  1. The headless docs pre-announce `--bare` becoming the default for `-p`, and bare mode
+     never reads `.mcp.json` — the billed `claude-code` e2e scenario in this repo's test
+     suite and the project-scope install story both need re-checking when that lands.
+  2. `${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`).
+  3. The same e2e scenario's `hasCompletedOnboarding` flag and the redundant
+     `enableAllProjectMcpServers` belt-and-suspenders are undocumented.

package/docs/research/mcp-compatibility.md

@@ -127,7 +127,9 @@ differences:
    spec says clients SHOULD support it whenever possible. Legacy SSE is never required —
    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`)
+   the `2024-11-05` floor set by Cline (v2 legacy support spans `2024-10-07`–`2025-11-25`;
+   `2024-10-07` is the pre-1.0 draft version string the SDK accepts for legacy
+   compatibility — it predates the spec's initial `2024-11-05` revision)
    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

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

@@ -54,7 +54,7 @@ MCP never carries conversation context to a server. The facts, per revision:
   human-reviewed
   ([sampling](https://modelcontextprotocol.io/specification/2025-11-25/client/sampling)). A server
   could only ask a model to *guess* intent — not obtain the user's question.
-- **Elicititation is interactive, not derivation.** `elicitation/create` asks the user a form/choice
+- **Elicitation is interactive, not derivation.** `elicitation/create` asks the user a form/choice
   question and waits ([2025-06-18+](https://modelcontextprotocol.io/specification/2025-06-18/client/elicitation));
   it requires client capability (only Codex in this matrix has it, per
   [mcp-compatibility.md](mcp-compatibility.md)) and an explicit round trip.
@@ -170,26 +170,25 @@ 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
 — the input schema is host-fixed to `query`, and the provider context has no session handle.**
 
-### Cline 0.0.13
-
-Closed source; the platform binary
-([@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13), ~119 MB)
-yielded the protocol facts already recorded — custom client negotiating `2024-11-05`,
-text-content-only results ([mcp-compatibility.md](mcp-compatibility.md)). No primary source
-documents whether the client validates tool arguments against `inputSchema` or mangles schemas;
-strings cannot prove a runtime behavior either way, so this is **undeterminable at the lock**. The
-2024-11-05 revision itself puts no validation obligation on clients and defines `arguments` as a
-free-form object, so there is no protocol-level obstacle to channel A — merely no evidence for or
-against host behavior. Channel B: none (MCP only, `paths` in hosts.jsonc).
-
 ## Proprietary hosts
 
-No proprietary host documents a context channel; the question is whether anything documents
+Closed-source hosts, from binary analysis (Cline) and official docs/changelogs (the
+rest). No proprietary host documents a context
+channel; the question is whether anything documents
 input-schema handling that would break an optional parameter.
 
 - **Claude Code 2.1.303.** The [MCP docs](https://code.claude.com/docs/en/mcp) say nothing about
@@ -203,6 +202,16 @@ input-schema handling that would break an optional parameter.
   preventing calling MCP tools that have nested references in their input schemas". Together these
   show the server's `inputSchema` is what the model provider sees and that arguments follow it;
   no host-side validation is ever mentioned. **A feasible by this evidence; B none.**
+- **Cline 0.0.13.** Closed source; the platform binary
+  ([@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13), ~119 MB)
+  yielded the protocol facts already recorded — custom client negotiating `2024-11-05`,
+  text-content-only results ([mcp-compatibility.md](mcp-compatibility.md)). No primary
+  source documents whether the client validates tool arguments against `inputSchema` or
+  mangles schemas; strings cannot prove a runtime behavior either way, so this is
+  **undeterminable at the lock**. The 2024-11-05 revision itself puts no validation
+  obligation on clients and defines `arguments` as a free-form object, so there is no
+  protocol-level obstacle to channel A — merely no evidence for or against host behavior.
+  Channel B: none (MCP only, `paths` in hosts.jsonc).
 - **Cursor 2026.10.08.** The [MCP docs](https://cursor.com/docs/mcp) describe tools only as
   "Functions for the AI model to execute" and say nothing about input schemas, validation, or
   context — and the protocol revision itself is unpinnable from primary sources
@@ -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.
@@ -282,7 +293,7 @@ negotiated revision in the matrix.
   [2025-11-25 tasks (experimental)](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/tasks)
 - [2026-07-28 overview (`_meta`, statelessness)](https://modelcontextprotocol.io/specification/2026-07-28/basic/index)
 
-### Open-source hosts
+### Open-source host sources
 
 - Codex: [rust-v0.163.0 tag](https://github.com/openai/codex/tree/rust-v0.163.0) —
   [mcp_tool_call.rs (argument parsing, no validation)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/core/src/mcp_tool_call.rs),
@@ -313,15 +324,15 @@ negotiated revision in the matrix.
   (Tool.Context, WebSearch.ProviderInput),
   [@opencode/client](https://registry.npmjs.org/@opencode/client/2.0.32)
   (session.context → SessionMessageInfo[], SessionMessageUser.text)
-- Cline: [@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13)
-  (manifest only; behavior undeterminable) and prior binary analysis recorded in
-  [mcp-compatibility.md](mcp-compatibility.md)
 
-### Proprietary hosts
+### Proprietary host sources
 
 - Claude Code: [changelog](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md)
   (entries 2.0.50, 2.1.30, 2.1.246, 2.1.300 — all ≤ the 2.1.303 lock),
   [MCP docs](https://code.claude.com/docs/en/mcp)
+- Cline: [@cline/cli-linux-x64 0.0.13](https://registry.npmjs.org/@cline/cli-linux-x64/0.0.13)
+  (manifest only; behavior undeterminable) and prior binary analysis recorded in
+  [mcp-compatibility.md](mcp-compatibility.md)
 - Cursor: [MCP docs](https://cursor.com/docs/mcp) (silent on the question)
 - Devin: [MCP overview](https://docs.devin.ai/cli/extensibility/mcp/overview),
   [changelog](https://docs.devin.ai/cli/changelog) (silent on the question)

package/docs/research/result-quality-passthrough.md

@@ -5,8 +5,8 @@ This note answers one question: through which channel can DeepSeek's per-result
 (string|null) — reach the **model** (not the human UI) on each host at its locked version? The
 repo filters on the first two in `src/core/search.ts` (thresholds default to off); at the
 research baseline it dropped all three before returning — the adapters now pass them through
-as a text marker plus a structured mirror (item 1 below is implemented as
-`formatQualityMarker`).
+as a text marker plus a structured mirror (the text marker of *What this means for this
+repo*, item 1, is implemented as `formatQualityMarker`).
 Related: [ori-question-sourcing.md](ori-question-sourcing.md) (input side),
 [search-inline-content.md](search-inline-content.md) (content volume).
 
@@ -47,7 +47,8 @@ The server-side validator (`@modelcontextprotocol/server` 2.3.1,
   `Output validation error: Tool <name> has an output schema but no structured content was
   provided` (JSON-RPC `InvalidParams`). Text-only results are not allowed for schema'd tools.
 - `structuredContent` is then validated against the schema; a mismatch is rejected the same way.
-- The v2 codec's SEP-2106 §4.3 auto-append (`appendTextFallbackForNonObject`) adds a
+- The v2 codec's SEP-2106 §4.3 auto-append (so named in the installed SDK's own source;
+  implemented as `appendTextFallbackForNonObject`) adds a
   `JSON.stringify(structuredContent)` TextContent block **only when `structuredContent` is a
   non-object** (primitive/array/null) and no text block exists. Object-shaped
   `structuredContent` gets **no** automatic text mirror — the server must mirror it itself to
@@ -108,7 +109,8 @@ From the official repo at tag `v2.0.32` (github.com/anomalyco/opencode, where `@
 - Every tool result then passes through `ToolOutput.truncate`:
   **`MAX_LINES = 2000`, `MAX_BYTES = 50 KiB`** (full output retained to a `tool-output/`
   file for 7 days) — [`packages/core/src/tool-output.ts`](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool-output.ts).
-  These caps were not previously recorded in [control-matrix.md](control-matrix.md).
+  These caps are also recorded in [control-matrix.md](control-matrix.md#opencode)'s
+  OpenCode section.
 
 ## What this means for this repo
 
@@ -128,9 +130,9 @@ From the official repo at tag `v2.0.32` (github.com/anomalyco/opencode, where `@
    The Pi adapter's extension `outputSchema` is safe as-is — Pi re-declares but does not
    validate it, and its `structuredContent` is event data.
 4. **New cap facts for the design margin:** OpenCode plugin results truncate at 2000 lines /
-   50 KiB (new), Pi extension tools bypass the MCP 20 KB truncation (already known), Claude
-   Code 25k tokens, Codex per-tool `output_token_limit` (default unpublished). None of these
-   bind at search-result volumes; they matter if [inline content](search-inline-content.md) is
+   50 KiB, Pi extension tools bypass the MCP 20 KB truncation, Claude Code caps output at
+   25k tokens, and Codex applies its per-tool `output_token_limit` (default unpublished).
+   None of these bind at search-result volumes; they matter if [inline content](search-inline-content.md) is
    ever enabled.
 
 ## Sources

package/docs/research/search-api-defaults.md

@@ -159,7 +159,8 @@ the current official docs** (checked 2026-10-21), nor in the November 2025 snaps
 page on the Internet Archive; the published truncation mechanism is the token-based
 `max_content_tokens` parameter above, with no published default.
 
-SDK layer (official repos, default branch):
+SDK layer (official repos, default branch at the 2026-10-21 check — moving heads, unlike
+the pinned firecrawl 4.50.0 above; re-pin to a tag before citing these constants later):
 
 | SDK | Default timeout | Default max retries | Source |
 | --- | --- | --- | --- |
@@ -180,7 +181,8 @@ From the official guide
 
 No relevance/authority score or filter is exposed on any web-search surface.
 
-SDK layer (official repos, default branch):
+SDK layer (official repos, default branch at the 2026-10-21 check — same moving-head
+caveat as the Anthropic SDK table above):
 
 | SDK | Default timeout | Default max retries | Source |
 | --- | --- | --- | --- |