mcp-context-cost 0.16.0 → 0.18.0

package/README.md

@@ -27,9 +27,13 @@ gate passed or not, so a later step can comment the number on the PR or publish
 **What do the MCP servers in your config cost you before you type anything — and what did
 that last config change add to every session you will ever run?**
 
-Every MCP server you wire into an agent injects its tool schemas into the model's context on
-every single request. You pay that whether or not the agent ends up using the tools, and no
-client shows you the number. Point `audit` at your own MCP config:
+Every MCP server you wire into an agent has to put its tool schemas somewhere. For a client
+with no deferral on record that is the model's context, on every single request, whether or
+not the agent ends up using the tools; for a client that defers them — Claude Code by default,
+and Cursor, Codex CLI and VS Code by their vendors' own records — it is a smaller session-start
+cost plus whatever the agent reaches for. Which of the two you are paying is a property of your
+client, not of the server, and no client shows you either number. Point `audit` at your own MCP
+config:
 
 ```bash
 npx -y mcp-context-cost audit
@@ -83,13 +87,25 @@ nobody runs.
 ### Where this cost is paid in full, and where it is deferred away
 
 Not every client puts every tool definition in context on every request, so the total above
-is not automatically your bill. Which client reads the config, and how that client is
-configured **on this machine**, decides it — and `audit` reads that rather than assuming it.
-
-**Clients with no default deferral on record** — Claude Desktop, Cursor, VS Code, Windsurf,
-Codex CLI, Gemini CLI, Zed, Kiro, Goose. The total is what every request carries, as in the
-example above. That sentence is an
-absence of a record about those clients, not a measurement of them, and the report says so
+is not automatically your bill. Which client reads the config decides it, and for Claude Code
+so does how that client is configured **on this machine** — which `audit` reads rather than
+assumes. No other client's posture is readable from a file this opens, so for those the report
+gives what their vendor is on record with, or says there is nothing on record, and claims
+neither as a measurement.
+
+**Clients whose vendor is on record as deferring** — Cursor (*dynamic context discovery*),
+Codex CLI (*tool search*), and VS Code, whose record is a pair of conditions rather than a
+default. For these the report prints what the vendor states, what that record leaves open, and
+the address and date of every source behind it. It stops where Claude Code's entry stops:
+nothing here measured any of them, and no config file this reads states their posture — so the
+total is what the definitions weigh, not a bill every request is known to carry, and not a
+saving either. Cursor's record is the reason this changed: its engineering blog described the
+mechanism on 2026-01-06 while its MCP configuration page, then and now, says nothing, and a
+rule that read only that page reported an absence of a record for eight months.
+
+**Clients with no default deferral on record** — Claude Desktop, Windsurf, Gemini CLI, Zed,
+Kiro, Goose. The total is what every request carries, as in the example above. That sentence is
+an absence of a record about those clients, not a measurement of them, and the report says so
 in those words.
 
 **Claude Code defers MCP tool definitions by default** (its **tool search**): they are not
@@ -105,7 +121,8 @@ deferral off in a settings file is not a machine running the default:
 | `ENABLE_TOOL_SEARCH=true` | same: every definition deferred |
 | `ENABLE_TOOL_SEARCH=false` | deferral off — every request carries the full total. In a settings `env` block that is the **string** `"false"`; the JSON boolean `false` is the last row, not this one |
 | `ENABLE_TOOL_SEARCH=auto` / `auto:N` | deferred only once definitions reach 10% / N% of the context window |
-| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set | tool search off — read first, because `ENABLE_TOOL_SEARCH` cannot override it |
+| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set to `1`, `true`, `yes` or `on` | tool search off — read first, because `ENABLE_TOOL_SEARCH` cannot override it |
+| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` set to `0`, `false`, `no` or `off` | it turned nothing off, so the read moves on and the rows above decide. It is a boolean flag in the client, not a marker whose presence is the signal |
 | `ANTHROPIC_BASE_URL` off `api.anthropic.com` | falls back to loading up front — consulted only while `ENABLE_TOOL_SEARCH` is unset |
 | anything else in `ENABLE_TOOL_SEARCH` | not a documented value, so nothing is claimed from it |
 | any of the three set, in a settings `env` block, to something that is not a string — a JSON boolean, a number, `null` | it is set there and what it is set to is unknown, so no posture is claimed: the report says whether these tokens are deferred cannot be said from it |
@@ -130,6 +147,41 @@ On a machine where none of them is set, the same stack reads:
     a tool whose _meta carries "anthropic/alwaysLoad": true, which this audit does not read from a capture
 ```
 
+**Do not take that table on trust — your own client will tell you.** Everything above is read
+from Anthropic's documentation, and documentation about someone else's product is exactly the
+kind of claim this project refuses to leave unchecked elsewhere. Claude Code writes its own
+decision to a debug log, before it sends anything, so you can check your machine rather than
+believe this page. In a directory with an `.mcp.json`:
+
+```bash
+claude --debug-file /tmp/cc.txt -p "ok"
+grep -E 'ToolSearch|Dynamic tool loading|Auto tool search' /tmp/cc.txt
+```
+
+Three line shapes answer three different questions:
+
+| the line | what it tells you |
+|---|---|
+| `[ToolSearch:optimistic] mode=…, ENABLE_TOOL_SEARCH=…, result=…` | which mode it picked at startup, and the value it read. **Optimistic is its own word for a guess** — it can be revised below |
+| `Dynamic tool loading: 0/N deferred tools included` | the one that settles it: how many of the `N` deferrable tools went into the request. `0/N` is deferral actually happening |
+| `[ToolSearch:optimistic] disabled: ANTHROPIC_BASE_URL=… is not a first-party Anthropic host` | the fallback in the table above, firing, in the client's own words |
+
+Read the *later* requests, not the first. A stdio server can finish connecting after the first
+request has already gone, so an early low count is a race rather than a finding.
+
+**The mode most likely to surprise you is `auto`.** It reads as the careful setting and it is the
+one that loads everything up front at ordinary sizes: below the threshold it does not defer, by
+design, and a line reading `Auto tool search disabled: … (threshold: …)` is that decision being
+made. The threshold is a *percentage of the context window*, so a model with a larger window has
+a proportionally larger one — pass `--context` to `audit` to compare against the window you
+actually run.
+
+None of this is free, and it is one trivial request. These are Claude Code's own debug lines
+rather than a documented interface, so they can change; the table above is what this project
+holds to a dated re-read. No other client discovered by `audit` writes anything comparable,
+which is why no other row here is a measurement: three of them get their vendor's own record,
+dated and addressed, and the rest an absence of one.
+
 Set `ENABLE_TOOL_SEARCH=false` in that shell and the same config reports the opposite —
 `loads every tool definition up front here`, naming the variable and the place it was read
 from. Deferring is also not free: what a deferring client *does* load at session start —
@@ -144,11 +196,13 @@ servers); it will not claim a posture the machine did not state readably, which
 refusals and not one — when two places set the same variable to different values, when a
 settings file exists and cannot be read, when the place that would decide sets the variable
 to something that is not a string, and when `ENABLE_TOOL_SEARCH` holds a value Claude Code
-does not document; and it will not pass an absence of a record off as a measurement. The
-first two print as unanswered questions. The third prints as an answer that names
-itself: for the nine discovered clients with no default on record — `claude-desktop`, `cursor`, `vscode`, `windsurf`, `codex`, `gemini`, `zed`, `kiro`, `goose` — the tokens are counted as
-loaded up front, and the report says so in those words, "an absence of a record about the
-client, not a measurement of it".
+does not document; and it will not pass an absence of a record off as a measurement, or a
+vendor's record off as one either. The first two print as unanswered questions. The third
+prints as an answer that names itself: for the six discovered clients with no default on
+record — `claude-desktop`, `windsurf`, `gemini`, `zed`, `kiro`, `goose` — the tokens are
+counted as loaded up front, and the report says so in those words, "an absence of a record
+about the client, not a measurement of it". For `cursor`, `codex` and `vscode` it prints the
+vendor's record with its dates and everything it leaves open, and claims no side.
 Full model, sources and dates: [METHODOLOGY §who pays the number](docs/METHODOLOGY.md#who-pays).
 
 **In CI**, make it a gate — the bundlesize move for agents:
@@ -235,7 +289,7 @@ prose every request carries — and only descriptions at or above the 90th perce
 
 ```
   suggest — descriptions at or above the 90th percentile of measured tools
-  (baseline 2026-09-05: 1,430 tools across 87 measured servers):
+  (baseline 2026-09-07: 1,430 tools across 87 measured servers):
     stub · wordy — 345 tokens: description 321 (p92), schema 14
       rewriting the description toward the measured median (27) would recover ≈294 tokens on every request
     1 of 2 tools sit inside the distribution — no advice where nothing is measurably unusual.
@@ -269,20 +323,21 @@ Flags: `--json` (full report on stdout, progress on stderr), `--budget N`,
 
 The number `audit` gives you is the same measurement, run across a curated set of public
 servers — which is how you can tell it is a measurement and not this tool's opinion. It also
-shows what you are choosing between: across the 87 servers measured, cost spans **1,700×**,
-from `postgres` at 32 tokens to `github` at 54,622. The table below is a
-sample of that range; the full range is in
+shows what you are choosing between: across the 87 servers measured, cost spans **1,700×** on
+the wire, from `postgres` at 32 tokens to `github` at 54,622 — of which a request carries
+10,735, and Claude counts those at 18,728. The table below is a sample of that range, ranked
+on the wire like every other list here; the full range is in
 [results/leaderboard.md](results/leaderboard.md).
 
-| server | context cost | tools |
-|---|---:|---:|
-| github (official) | **54,622 tokens** | 44 |
-| xcodebuildmcp | 26,594 | 24 |
-| brave-search | 25,487 | 8 |
-| notion | 17,500 | 24 |
-| playwright *(4.8M installs/week)* | 4,024 | 24 |
-| filesystem (reference) | 2,823 | 14 |
-| markitdown | 64 | 1 |
+| server | context cost (wire) | mapped | on Claude | tools |
+|---|---:|---:|---:|---:|
+| github (official) | **54,622 tokens** | 10,735 | 18,728 | 44 |
+| xcodebuildmcp | 26,594 | 2,676 | 5,335 | 24 |
+| brave-search | 25,487 | 8,278 | 13,762 | 8 |
+| notion | 17,500 | 17,163 | 33,560 | 24 |
+| playwright *(4.8M installs/week)* | 4,024 | 3,402 | 6,172 | 24 |
+| filesystem (reference) | 2,823 | 1,665 | 3,115 | 14 |
+| markitdown | 64 | 64 | 404 | 1 |
 
 *(87 of 107 popular servers measured, each row dated by its own most recent sweep — full table in
 [results/leaderboard.md](results/leaderboard.md); every failure is listed with its reason.
@@ -308,12 +363,14 @@ the cost before they install rather than after:
 
 The badge counts every byte a server returns. An Anthropic request carries only `name`,
 `description`, and `input_schema` — and counts them with a denser tokenizer. Both effects are
-now measured against a pinned model and published beside the badge, and they do not cancel:
+now measured against a pinned model and published beside the badge, and they do not cancel.
+The middle column is what a request actually carries, counted with the badge's own tokenizer,
+so the two effects are separated rather than folded together:
 
-| server | badge (o200k) | Claude (`claude-opus-5`) | |
-|---|---:|---:|---|
-| github | 54,622 | **18,728** | most of the capture is `annotations`/`outputSchema` metadata Claude never sees |
-| notion | 17,500 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
+| server | badge (o200k) | mapped | Claude (`claude-opus-5`) | |
+|---|---:|---:|---:|---|
+| github | 54,622 | 10,735 | **18,728** | 78% of the capture is `icons` metadata Claude never sees |
+| notion | 17,500 | 17,163 | **33,560** | almost no metadata to drop, so the tokenizer difference dominates |
 
 So the heaviest server on the badge is not the heaviest server on Claude. Per-server
 breakdowns are on each [detail page](https://athakur3.github.io/mcp-context-cost/servers/);
@@ -472,10 +529,7 @@ color bands are frozen against the observed distribution of the first full sweep
 
 ## Status
 
-Active. Every row carries the date of its own most recent measurement, and what the data
-says as a whole is written up, dated, in
-[The State of MCP Context Cost](https://athakur3.github.io/mcp-context-cost/state-of-mcp-context-cost)
-(September 2026). Two
+Active. Every row carries the date of its own most recent measurement. Two
 weekly jobs re-measure the set — the `memory` reference server on Mondays, and a rotating
 third of the list on Wednesdays, so every row comes round within three weeks. Read each row's
 date as the date it means, and don't take the cadence on trust — the build history is

package/dist/audit/audit.js

@@ -268,6 +268,20 @@ export function buildReport(configs, measured, opts = {}) {
                     });
                     continue;
                 }
+                if (probe.kind === 'protocol-mismatch') {
+                    // The endpoint works. What it refused is the revision this audit
+                    // sends, which is a fact about this harness — so the row says that,
+                    // and not that nothing answered. Wired here explicitly because the
+                    // block below reads anything it has not tested as open and hands it
+                    // to the bridge.
+                    skipped.push({
+                        ...base,
+                        ...none,
+                        status: 'protocol-mismatch',
+                        notes: `${s.url} answered ${probe.detail} — this audit speaks a revision it does not`,
+                    });
+                    continue;
+                }
                 if (probe.kind === 'unreachable') {
                     skipped.push({ ...base, ...none, status: 'unreachable', notes: `${s.url}: ${probe.detail}` });
                     continue;
@@ -527,6 +541,31 @@ function thresholdAssumptionLines(d) {
         '  side of it depending on which model the client runs.',
     ];
 }
+/**
+ * One indented item, wrapped to a terminal width with a hanging indent.
+ *
+ * The records these print are prose, not labels, and the alternative was
+ * hand-wrapping sentences in the data — which puts the line breaks of a report
+ * inside the thing the report is quoting, and moves them every time a word
+ * changes.
+ */
+function bullet(text, width = 92) {
+    const out = [];
+    let line = '';
+    for (const word of text.split(' ')) {
+        const next = line ? `${line} ${word}` : word;
+        if (line && next.length + 4 > width) {
+            out.push(line);
+            line = word;
+        }
+        else {
+            line = next;
+        }
+    }
+    if (line)
+        out.push(line);
+    return out.map((l, i) => (i === 0 ? `    ${l}` : `      ${l}`));
+}
 /** Where a threshold is in play, the unknown size is the whole verdict. */
 const SIDE_UNKNOWN = [
     '  either direction — which side of the threshold this stack falls on cannot be',
@@ -583,6 +622,38 @@ function deferralLines(d, skippedNames) {
             lines.push(...sharedMeasurementLines(d, skippedNames, SIZE_UNKNOWN));
         return lines;
     }
+    // A vendor's record, printed with everything it does not settle attached to
+    // it. The shape is Claude Code's, minus the half this cannot have: what is on
+    // record, that nothing here measured it, and — because no config file on the
+    // audited machine states the posture — no verdict about which way this stack
+    // goes. Reporting the total as deferred away would be the same error the
+    // absence-of-a-record rule was written against, in the opposite direction.
+    if (d.mode === 'deferral-on-record') {
+        const r = d.record;
+        // The mode without its record is not a milder version of this answer, it is
+        // no answer: everything below is quotation. Falling through from here would
+        // reach the threshold branch and print Claude Code's arithmetic over a
+        // client that has none.
+        if (!r) {
+            lines.push(`  ${d.client} is on record as deferring tool definitions, and the record`);
+            lines.push('  itself did not reach this report — so nothing is claimed about who pays.');
+            return lines;
+        }
+        for (const l of r.states)
+            lines.push(`  ${l}`);
+        for (const l of r.notReadable)
+            lines.push(`  ${l}`);
+        lines.push('  So read this total as what the definitions weigh, not as a bill every');
+        lines.push('  request is known to carry — and not as a saving either:');
+        for (const c of r.conditions)
+            lines.push(...bullet(c));
+        lines.push('  What the vendor is on record with, and when it was read:');
+        for (const src of r.sources)
+            lines.push(...bullet(src));
+        if (d.sharedMeasurements > 0)
+            lines.push(...sharedMeasurementLines(d, skippedNames, SIZE_UNKNOWN));
+        return lines;
+    }
     if (d.mode === 'setting-unrecognized') {
         lines.push(`  ${d.setting?.variable} is set to "${d.setting?.value}" on this machine, which is not`);
         lines.push('  one of the values Claude Code documents (unset, true, false, auto, auto:N).');

package/dist/audit/config.d.ts

@@ -119,13 +119,43 @@ export interface SettingsCandidate {
  * Order is Claude Code's documented settings precedence (enterprise managed
  * policy, then project-local, then project, then user), read 2026-08-20. Paths
  * in, candidates out — nothing here touches a disk.
+ *
+ * The Windows directory is `C:\Program Files\ClaudeCode`, not `%ProgramData%`.
+ * `code.claude.com/docs/en/managed-settings.md`, read 2026-09-08, names the
+ * system directory per platform and then says in as many words: "Claude Code
+ * doesn't read the legacy Windows path
+ * `C:\ProgramData\ClaudeCode\managed-settings.json`". This opened that legacy
+ * path and no other, so on a managed Windows machine it read a file that
+ * decides nothing and never opened the one that does.
+ *
+ * Not modelled, and named here so the gap is on record rather than implied:
+ * WSL can be told to inherit the Windows policy chain, and whether it does
+ * turns on a key in a file this may not have read.
  */
 export declare function settingsCandidates(env: {
     home: string;
     cwd: string;
     platform: NodeJS.Platform;
-    programData?: string;
 }): SettingsCandidate[];
+/**
+ * The `managed-settings.d/*.json` drop-ins beside the managed settings file.
+ *
+ * `code.claude.com/docs/en/managed-settings.md`, read 2026-09-08: the file
+ * source is "`managed-settings.d/*.json` and `managed-settings.json` merged
+ * together" in the same system directory — one tier, not two. Reading only
+ * `managed-settings.json` is the same shape of miss as reading only the shell
+ * was: a place the client takes these variables from, never opened.
+ *
+ * Unlike `settingsCandidates` this one lists a directory, which is why it is a
+ * separate function called from `discoverSettings` rather than folded in there:
+ * that one promises paths in, candidates out, and nothing touching a disk.
+ *
+ * A directory that exists and cannot be listed yields the directory itself as a
+ * candidate, so it is read as one `unreadable` source rather than as silence.
+ * What it holds is unknown, and an unknown in the tier that outranks every
+ * other file is not the same as a tier that sets nothing.
+ */
+export declare function managedDropInCandidates(managedSettingsPath: string, list?: (dir: string) => string[]): SettingsCandidate[];
 /**
  * Read what each settings file sets, of the variables that decide deferral.
  *

package/dist/audit/config.js

@@ -30,8 +30,8 @@
  * name) are held to the same rule: sent with the request, never reported —
  * only `headerNames` is.
  */
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { parse as parseToml } from 'smol-toml';
 import { parse as parseYaml } from 'yaml';
 import { TOOL_SEARCH_VARS, } from './deferral.js';
@@ -348,13 +348,25 @@ export function loadConfigs(candidates, cwd, processEnv = process.env) {
  * Order is Claude Code's documented settings precedence (enterprise managed
  * policy, then project-local, then project, then user), read 2026-08-20. Paths
  * in, candidates out — nothing here touches a disk.
+ *
+ * The Windows directory is `C:\Program Files\ClaudeCode`, not `%ProgramData%`.
+ * `code.claude.com/docs/en/managed-settings.md`, read 2026-09-08, names the
+ * system directory per platform and then says in as many words: "Claude Code
+ * doesn't read the legacy Windows path
+ * `C:\ProgramData\ClaudeCode\managed-settings.json`". This opened that legacy
+ * path and no other, so on a managed Windows machine it read a file that
+ * decides nothing and never opened the one that does.
+ *
+ * Not modelled, and named here so the gap is on record rather than implied:
+ * WSL can be told to inherit the Windows policy chain, and whether it does
+ * turns on a key in a file this may not have read.
  */
 export function settingsCandidates(env) {
     const { home, cwd, platform } = env;
     const managed = platform === 'darwin'
         ? '/Library/Application Support/ClaudeCode/managed-settings.json'
         : platform === 'win32'
-            ? join(env.programData ?? 'C:\\ProgramData', 'ClaudeCode', 'managed-settings.json')
+            ? 'C:\\Program Files\\ClaudeCode\\managed-settings.json'
             : '/etc/claude-code/managed-settings.json';
     return [
         { scope: 'managed-settings', path: managed },
@@ -363,6 +375,40 @@ export function settingsCandidates(env) {
         { scope: 'user-settings', path: join(home, '.claude', 'settings.json') },
     ];
 }
+/**
+ * The `managed-settings.d/*.json` drop-ins beside the managed settings file.
+ *
+ * `code.claude.com/docs/en/managed-settings.md`, read 2026-09-08: the file
+ * source is "`managed-settings.d/*.json` and `managed-settings.json` merged
+ * together" in the same system directory — one tier, not two. Reading only
+ * `managed-settings.json` is the same shape of miss as reading only the shell
+ * was: a place the client takes these variables from, never opened.
+ *
+ * Unlike `settingsCandidates` this one lists a directory, which is why it is a
+ * separate function called from `discoverSettings` rather than folded in there:
+ * that one promises paths in, candidates out, and nothing touching a disk.
+ *
+ * A directory that exists and cannot be listed yields the directory itself as a
+ * candidate, so it is read as one `unreadable` source rather than as silence.
+ * What it holds is unknown, and an unknown in the tier that outranks every
+ * other file is not the same as a tier that sets nothing.
+ */
+export function managedDropInCandidates(managedSettingsPath, list = readdirSync) {
+    const dir = join(dirname(managedSettingsPath), 'managed-settings.d');
+    if (!existsSync(dir))
+        return [];
+    let names;
+    try {
+        names = list(dir);
+    }
+    catch {
+        return [{ scope: 'managed-drop-in', path: dir }];
+    }
+    return names
+        .filter((n) => n.endsWith('.json') && !n.startsWith('.'))
+        .sort()
+        .map((n) => ({ scope: 'managed-drop-in', path: join(dir, n) }));
+}
 /**
  * Read what each settings file sets, of the variables that decide deferral.
  *

package/dist/audit/deferral.d.ts

@@ -46,10 +46,15 @@
  *     the exception below already names only the earlier models. (2) Under
  *     `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`, "your organization can keep
  *     tool search on through managed settings, on Claude Code v2.1.227 or
- *     later" — on a direct connection or a gateway, not on a cloud provider.
- *     This audit reads the managed settings file for the three variables and
- *     nothing else, so that override is not read here and the variable is
- *     still resolved as "off". (3) `alwaysLoad: true` is an entry field on
+ *     later" — on a direct connection or a gateway set with `ANTHROPIC_BASE_URL`,
+ *     and with no effect on a cloud provider or a Claude apps gateway sign-in
+ *     (`code.claude.com/docs/en/llm-gateway-protocol.md`, read 2026-09-08).
+ *     This IS read as of 2026-09-08: `resolveToolSearchSources` looks at the
+ *     administrator tier, and where that tier sets `ENABLE_TOOL_SEARCH` to a
+ *     value the vendor does not document, the disabling variable stops
+ *     deciding and the posture is refused. The value that arms the override is
+ *     in no vendor document, so none is named here and nothing is claimed about
+ *     what it does. (3) `alwaysLoad: true` is an entry field on
  *     every server type, and a tool can carry `"anthropic/alwaysLoad": true`
  *     in its `_meta`. The entry form is read from the config now
  *     (`DeferralServer.alwaysLoad`) and counted rather than listed; the
@@ -58,13 +63,29 @@
  *     a deferring session loads at start — noted beside the session-start
  *     metric in METHODOLOGY, not applied to any number here.
  *
- * No default deferral is on record here for the other clients this tool
- * discovers — Claude Desktop, Cursor, VS Code, Windsurf, and from 2026-09-06
- * Codex CLI, Gemini CLI, Zed, Kiro and Goose, whose configuration pages were
- * read that day and say nothing about deferring tool definitions. That is an
- * absence of a record, not a measurement of those clients, and it is printed
- * as such — the same rule the rest of this project follows for a value it has
- * not observed.
+ * The other clients this tool discovers split in two, and what separates them
+ * is what counts as a record. Until 2026-09-07 the rule read one surface — each
+ * client's own MCP configuration page — and reported an absence of a record for
+ * every client whose page did not mention deferring. Three of those clients say
+ * the opposite elsewhere, on surfaces their own vendors control, the earliest of
+ * them dated eight months before that page was read. So the rule now takes four
+ * kinds of first-party statement, in METHODOLOGY §who-pays: the configuration
+ * page, the vendor's dated blog or changelog, a named staff account on the
+ * vendor's own forum, and the client's public source — a merged pull request or
+ * a settings default in the shipping tree. None of the four is a measurement.
+ *
+ *   - `DEFERRAL_ON_RECORD` — Cursor, Codex CLI, VS Code. The vendor states, or
+ *     the vendor's source shows, that definitions are deferred. What is printed
+ *     is close to Claude Code's honest shape and stops in the same place: the
+ *     vendor says so, this audit has not measured it, the conditions it depends
+ *     on are listed rather than resolved, and for none of the three does a file
+ *     this audit reads state the posture.
+ *   - `NO_DEFERRAL_ON_RECORD` — Claude Desktop, Windsurf, Gemini CLI, Zed, Kiro,
+ *     Goose. Still an absence of a record and printed as such, and now an
+ *     absence that was looked for: the three of them that are open source were
+ *     searched for a tool-search or deferral mechanism on 2026-09-07 and none
+ *     was found, while Claude Desktop, Windsurf and Kiro are closed and only
+ *     their pages have been read.
  */
 import type { DivergenceRun } from '../core/divergence.js';
 /** Share of the context window at which deferral activates under `auto`. */
@@ -89,7 +110,9 @@ export declare function toolSearchEnv(env: Record<string, string | undefined>):
  * are NOT loaded up front at any size" — at a machine that had switched
  * deferral off in `~/.claude/settings.json`.
  */
-export type ToolSearchScope = 'shell' | 'managed-settings' | 'local-settings' | 'project-settings' | 'user-settings';
+export type ToolSearchScope = 'shell' | 'managed-settings'
+/** A `managed-settings.d/*.json` drop-in: the managed file's own tier, not a rank below it. */
+ | 'managed-drop-in' | 'local-settings' | 'project-settings' | 'user-settings';
 /** What `source` says for the process environment, which has no path. */
 export declare const SHELL_SOURCE = "(shell environment)";
 export interface ToolSearchSource {
@@ -152,6 +175,11 @@ export type DeferralMode =
  | 'setting-unresolved'
 /** A client we know about, with no default deferral on record. */
  | 'no-deferral-on-record'
+/**
+ * A client whose vendor states, or whose source shows, that it defers tool
+ * definitions — unmeasured here, and not readable from the config either.
+ */
+ | 'deferral-on-record'
 /** `--config <path>`: the file was read, but which client reads it is unknown. */
  | 'client-unknown';
 /** How the mode was decided — printed, so a reader can check it against their own shell. */
@@ -321,6 +349,54 @@ export declare const BAND_PRECISION = 2;
  *   servers than were measured is a fabricated number rather than an old one.
  */
 export declare function bandSnapshotProblem(snapshot: Pick<WireToClientRatio, 'low' | 'high' | 'servers'>, derived: Pick<WireToClientRatio, 'low' | 'high' | 'servers'>): string | null;
+/**
+ * The passages on the vendor's own pages that this file's model of tool search
+ * rests on, and the rule for deciding whether they still say it.
+ *
+ * What rots here is not the client. It is these pages: the model is a reading
+ * of them, they have already moved host once under this project, and the whole
+ * of `resolveToolSearch` is downstream of four sentences. So the watch checks
+ * the sentences rather than a page hash — a hash of a documentation page is red
+ * every week for a typo and teaches everyone to ignore it.
+ *
+ * `tools/watch-tool-search-docs.ts` is the half that fetches. This half is the
+ * rule, offline and under test, the same split as `src/core/protocol.ts` and
+ * its spec watch.
+ */
+export interface ToolSearchDocClaim {
+    /** The page it was read from. */
+    url: string;
+    /** What this file does because of it, so a drift report says what broke. */
+    because: string;
+    /** Text that must still be on that page. Compared with whitespace collapsed. */
+    quote: string;
+}
+/** When every claim below was last read against the live page. */
+export declare const TOOL_SEARCH_DOC_READ_ON = "2026-09-08";
+export declare const ENV_VARS_DOC = "https://code.claude.com/docs/en/env-vars.md";
+export declare const GATEWAY_DOC = "https://code.claude.com/docs/en/llm-gateway-protocol.md";
+export declare const MANAGED_SETTINGS_DOC = "https://code.claude.com/docs/en/managed-settings.md";
+export declare const TOOL_SEARCH_DOC_CLAIMS: ToolSearchDocClaim[];
+/**
+ * The variables that page names as reading any non-empty value, read on the date
+ * above. The one that matters is the one that is NOT here.
+ */
+export declare const ANY_NON_EMPTY_VARS: string[];
+/**
+ * The variable names in that exception list, or null when the list could not be
+ * found in the shape this knows how to read — which is a reason to look, not a
+ * reason to report the list unchanged.
+ */
+export declare function anyNonEmptyVars(page: string): string[] | null;
+/**
+ * What is wrong with the live pages, in words. Empty means the model still has
+ * its sources.
+ *
+ * A page that could not be fetched is reported, never skipped: a watch that is
+ * green when it is blind is worse than no watch, which is the rule the spec
+ * watch is built on and the same one here.
+ */
+export declare function toolSearchDocProblems(pages: Map<string, string | null>): string[];
 /** Derive the band from a supplied divergence run, falling back to the published one. */
 export declare function wireToClientRatio(run?: DivergenceRun | null): WireToClientRatio;
 /** One measured server, as the deferral arithmetic needs it. */
@@ -434,6 +510,12 @@ export interface DeferralVerdict {
     sharedMeasurements: number;
     /** Conditions this cannot read, under which a deferring client pays in full. */
     exceptions: string[];
+    /**
+     * What the client's vendor is on record as doing, where that is not Claude
+     * Code and a record exists. Null in every other mode, including the absence
+     * of a record, which is a different fact and is printed as one.
+     */
+    record: DeferralRecord | null;
     /**
      * Servers in this scope pinned `alwaysLoad: true` in their entry, and their
      * wire tokens. Read from the config, so it is stated rather than listed as a
@@ -444,6 +526,27 @@ export interface DeferralVerdict {
         tokens: number;
     };
 }
+/**
+ * What a vendor is on record as doing, for a client this audit cannot measure.
+ *
+ * Every line here is printed, so every line is written to be checked: the claim
+ * is the vendor's, the conditions are the ones the vendor's own record leaves
+ * open, and the sources carry the address and the date they were read at. What
+ * this type deliberately cannot express is a verdict. A record establishes what
+ * a vendor says or ships; nothing in it says what a session paid.
+ */
+export interface DeferralRecord {
+    /** The vendor's own name for the mechanism, so a reader can look it up. */
+    mechanism: string;
+    /** What the record establishes. Lines, wrapped for the report. */
+    states: string[];
+    /** Why the posture still cannot be read off the audited machine. */
+    notReadable: string[];
+    /** What the record leaves open — printed as conditions, never resolved. */
+    conditions: string[];
+    /** First-party sources, each with the date it was read. */
+    sources: string[];
+}
 /**
  * Read one session's deferral position. Pure arithmetic over a built scope — no
  * config file is re-read and no server is launched. The environment is passed