diff --git a/CHANGELOG.md b/CHANGELOG.md
index ac9657062..4b4765c38 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -87,6 +87,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * **telemetry:** anonymous usage telemetry is now **opt-in** (off by default) instead of opt-out. Nothing is collected or sent unless you set `HEADROOM_TELEMETRY=on` or pass `--telemetry` to `headroom proxy` / `headroom install apply`. `is_telemetry_enabled()` is fail-closed — only explicit on-values (`on`/`true`/`1`/`yes`/`enable`/`enabled`) enable it; unset, empty, or unrecognized values stay disabled. The existing `--no-telemetry` flag and `HEADROOM_TELEMETRY=off` remain accepted for back-compat, and install manifests now write the `HEADROOM_TELEMETRY` value explicitly so generated deployments are unambiguous.
 * **ccr:** `headroom_stats` now labels its formatted proxy output as a rolling/window-scoped session and adds a lifetime savings section from `/stats persistent_savings.lifetime` when present, while keeping existing summary structure and fallback JSON output behavior.
+* **docs/claude:** document that `ENABLE_TOOL_SEARCH=true` is correct for the standalone Claude CLI through Headroom but currently breaks tool-result rendering in Anthropic's VSCode extension webview, and point persistent-install users at the manifest override to set `tool_envs.claude.ENABLE_TOOL_SEARCH` to `"false"` for that target ([#2028](https://github.com/headroomlabs-ai/headroom/issues/2028)).
 
 ### Features
 
diff --git a/docs/content/docs/persistent-installs.mdx b/docs/content/docs/persistent-installs.mdx
index eecf6e118..b2d991843 100644
--- a/docs/content/docs/persistent-installs.mdx
+++ b/docs/content/docs/persistent-installs.mdx
@@ -133,6 +133,20 @@ The Python-native `headroom wrap ...` flow checks for a matching persistent depl
 
 The Docker-native host wrapper does **not** yet reuse or recover persistent profiles automatically; it still starts a fresh proxy container unless you opt into `--no-proxy`.
 
+## Claude Code VSCode extension caveat
+
+Persistent Claude deployments default to `ENABLE_TOOL_SEARCH=true` because the
+standalone Claude CLI benefits from deferred tool schemas.
+
+Anthropic's VSCode extension currently does not render those deferred-tool content
+blocks correctly through Headroom and can show `unsupported content type` in the
+webview. If your persistent install targets Claude Code inside VSCode, edit
+`~/.headroom/deploy/<profile>/manifest.json`, set
+`tool_envs.claude.ENABLE_TOOL_SEARCH` to `"false"`, then restart the deployment.
+
+Keep `ENABLE_TOOL_SEARCH=true` for the standalone `claude` CLI unless you hit the
+same renderer limitation there.
+
 ## Docker-native relationship
 
 The Docker-native host wrapper and the Python install CLI solve different layers of the runtime story:
diff --git a/docs/content/docs/troubleshooting.mdx b/docs/content/docs/troubleshooting.mdx
index fc4d958f6..04cf769b7 100644
--- a/docs/content/docs/troubleshooting.mdx
+++ b/docs/content/docs/troubleshooting.mdx
@@ -183,6 +183,15 @@ When deferral is off, the proxy log also prints a one-time hint naming the fix.
 
 See [issue #746](https://github.com/chopratejas/headroom/issues/746) for the full analysis.
 
+<Callout type="warning" title="Claude Code VSCode extension caveat">
+  Anthropic's VSCode extension webview does not currently render the deferred-tool
+  content blocks that `ENABLE_TOOL_SEARCH=true` enables through Headroom. Tool
+  results can show up as `unsupported content type` in the extension even though
+  the standalone `claude` CLI works correctly. If you use Claude Code inside
+  VSCode, set `ENABLE_TOOL_SEARCH=false` for that target and restart the Headroom
+  deployment. See [issue #2028](https://github.com/headroomlabs-ai/headroom/issues/2028).
+</Callout>
+
 ## Remote Control unavailable through custom ANTHROPIC_BASE_URL
 
 **Symptom**: When Claude Code runs with `ANTHROPIC_BASE_URL` set to a custom host (for example, Headroom), the Remote Control menu is absent.