docs: document Claude VSCode deferred-tool rendering caveat (#2045)

## Description

Headroom already documents why `ENABLE_TOOL_SEARCH=true` matters for
Claude Code through a custom `ANTHROPIC_BASE_URL`, but it does not
document the current VSCode extension rendering failure on the
deferred-tool content blocks that setting can surface. This adds a
narrow docs warning and workaround for the VSCode path without changing
the CLI default that still helps the main Claude Code flow.

Refs #2028

## Type of Change

- [x] Documentation update
- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Document the Claude Code VSCode extension `unsupported content type`
failure mode.
- Explain when to set `ENABLE_TOOL_SEARCH=false` as a workaround.
- Keep the existing default guidance for Claude CLI users unchanged.

## Testing

- [x] Unit tests pass
- [ ] Linting passes
- [ ] Type checking passes
- [ ] New tests added for new functionality when applicable
- [x] Manual testing performed

### Test Output

```text
uv run --no-sync pytest tests/test_cli_doctor.py -q

============================= test session starts =============================
platform win32 -- Python 3.12.13, pytest-9.0.3, pluggy-1.6.0
rootdir: D:\Repos\headroom-pr-2028-claude-vscode-tool-search-docs
configfile: pyproject.toml
plugins: anyio-4.12.1, langsmith-0.9.3, asyncio-1.3.0, cov-7.0.0
asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 51 items

tests\test_cli_doctor.py ............................................... [ 92%]
....                                                                     [100%]

============================= 51 passed in 0.67s ==============================
```

## Real Behavior Proof

- Environment: Windows, Python 3.12.13, docs-only change with no LLM
provider involved
- Exact command / steps: `uv run --no-sync pytest
tests/test_cli_doctor.py -q`
- Observed result: All 51 `test_cli_doctor.py` tests pass, confirming
the existing `headroom doctor` CLI behavior is unchanged by the new
VSCode troubleshooting docs
- Not tested: live rendering in the Claude Code VSCode extension

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Additional Notes

The extension renderer bug is upstream. This PR only makes the current
Headroom behavior explicit and gives users the supported workaround.

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
 

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:

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.