feat: add first-class CCS WebSearch runtime

docs/project-overview-pdr.md

@@ -35,7 +35,7 @@ CCS provides:
 3. **AI Providers**: Dedicated CLIProxy dashboard for Gemini, Codex, Claude, Vertex, and OpenAI-compatible API-key families
 4. **API Profiles**: GLM, Kimi, OpenRouter, any Anthropic-compatible API
 5. **Visual Dashboard**: React SPA for configuration management
-6. **Automatic WebSearch**: Real backend fallback chain for third-party providers
+6. **Automatic WebSearch**: First-class local WebSearch tool with deterministic provider chain for third-party providers
 7. **Usage Analytics**: Token tracking, cost analysis, model breakdown
 8. **Official Claude Channels**: Runtime auto-enable plus dashboard token/config flow for Telegram, Discord, and macOS-only iMessage
 
@@ -93,7 +93,8 @@ CCS provides:
 - Validate symlinks and permissions
 
 ### FR-007: WebSearch Fallback
-- Intercept WebSearch for third-party profiles that cannot reach Anthropic's native tool
+- Expose a CCS-managed local WebSearch tool for third-party profiles that cannot reach Anthropic's native tool
+- Suppress native `WebSearch` on third-party launches so Claude uses the CCS-owned path
 - Support Exa, Tavily, Brave, and DuckDuckGo real search backends
 - Keep Gemini CLI, OpenCode, and Grok as optional legacy fallback
 - Graceful fallback chain

docs/project-roadmap.md

@@ -1,6 +1,6 @@
 # CCS Project Roadmap
 
-Last Updated: 2026-03-28
+Last Updated: 2026-03-30
 
 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans.
 
@@ -41,6 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 
 ### Recent Fixes
 
+- **2026-03-30**: **#862** Third-party WebSearch now uses a first-class CCS-managed MCP tool path instead of relying on a denied native Anthropic `WebSearch` call as the normal UX. CCS provisions `ccs-websearch` into `~/.claude.json`, syncs it into isolated account configs when needed, suppresses native `WebSearch` on third-party launches, preserves the provider order `Exa -> Tavily -> Brave -> DuckDuckGo -> legacy CLI fallback`, and keeps the old hook runtime only as shared provider plumbing plus compatibility fallback. Uninstall cleanup now also removes the managed WebSearch MCP runtime.
 - **2026-03-28**: **#773** CCS now ships a dedicated `Compatible -> Codex CLI` dashboard route with a real split-view control center. The page detects the local Codex binary, keeps overview/docs guidance, and adds guided editors for the user-owned `~/.codex/config.toml` layer: top-level runtime defaults, project trust, profiles, model providers, MCP servers, and supported feature flags. Structured saves intentionally normalize TOML formatting and drop comments, so the raw editor remains the fidelity escape hatch. Follow-up fixes added immediate raw snapshot refresh, refresh/discard recovery for stale raw drafts, dirty raw-editor guarding for structured controls, project-trust path validation, read-only handling for unreadable config files, preservation of unsupported upstream values such as granular `approval_policy`, and feature reset-to-default support. CCS still warns that transient runtime overrides such as `codex -c key=value` and `CCS_CODEX_API_KEY` may change effective behavior without persisting into the file.
 - **2026-03-27**: WebSearch dashboard cards now manage Exa, Tavily, and Brave API keys inline instead of relying on a separate manual env step. CCS stores those secrets through `global_env`, reflects masked key state in `/api/websearch`, and counts dashboard-managed keys as ready in the WebSearch status flow.
 - **2026-03-27**: **#812** CCS now includes a first-class `ccs docker` command suite for self-hosting the integrated Dashboard + CLIProxy stack. The CLI can stage bundled Docker assets locally or to a remote `--host` over SSH, report compose/supervisor status, stream CCS or CLIProxy logs, and run in-container update flows without relying on ad-hoc deployment scripts.

docs/websearch.md

@@ -1,6 +1,6 @@
 # WebSearch Configuration Guide
 
-Last Updated: 2026-03-27
+Last Updated: 2026-03-30
 
 CCS provides automatic web search for third-party profiles that cannot access Anthropic's native WebSearch API.
 
@@ -12,7 +12,7 @@ Native Claude subscription accounts still use Anthropic's server-side WebSearch
 
 ### Third-Party Profiles
 
-Third-party profiles cannot execute Anthropic's server-side WebSearch because the tool never reaches their backend. CCS now solves that by intercepting WebSearch and running real local search providers directly.
+Third-party profiles cannot execute Anthropic's server-side WebSearch because the tool never reaches their backend. CCS now solves that by provisioning a first-class local MCP tool, suppressing native `WebSearch` for those launches, and running real local search providers directly.
 
 ## Architecture
 
@@ -20,30 +20,37 @@ Third-party profiles cannot execute Anthropic's server-side WebSearch because th
 ┌──────────────────────────────────────────────────────────────┐
 │                   Claude Code CLI                           │
 │                                                              │
-│  WebSearch Tool Request                                      │
+│  Search Request                                              │
 │       │                                                      │
 │       ├── Native Claude Account? → Anthropic WebSearch API  │
 │       │                                                      │
-│       └── Third-party Profile? → PreToolUse Hook            │
+│       └── Third-party Profile? → native WebSearch disabled  │
 │                                   │                          │
-│                                   ├── 1. Exa Search API      │
-│                                   ├── 2. Tavily Search API   │
-│                                   ├── 3. Brave Search API    │
-│                                   ├── 4. DuckDuckGo HTML     │
-│                                   └── 5. Legacy CLI fallback │
-│                                      (Gemini/OpenCode/Grok)  │
+│                                   └── CCS MCP tool           │
+│                                       ccs-websearch.search   │
+│                                              │               │
+│                                              ├── 1. Exa      │
+│                                              ├── 2. Tavily   │
+│                                              ├── 3. Brave    │
+│                                              ├── 4. DuckDuckGo│
+│                                              └── 5. Legacy CLI│
+│                                                 fallback      │
+│                                                 (Gemini/      │
+│                                                  OpenCode/    │
+│                                                  Grok)        │
 └──────────────────────────────────────────────────────────────┘
 ```
 
 ## Why This Changed
 
-The previous design asked another model CLI to perform web search and summarize the answer. That was brittle:
+The previous design asked another model CLI to perform web search and summarize the answer. A later compatibility path also depended on a denied native-tool hook. Both were brittle:
 
 - CLI syntax changed upstream
 - auth state varied per tool
 - prompt/tool behavior drifted across releases
+- hook-shaped denial output produced awkward host UX
 
-The new flow matches the `goclaw` model more closely: web search is treated as a first-class deterministic capability, not an LLM-to-LLM workaround.
+The new flow matches the `goclaw` model more closely: web search is treated as a first-class deterministic capability, not an LLM-to-LLM workaround or a denied native tool call.
 
 ## Providers
 
@@ -109,8 +116,14 @@ websearch:
 | `TAVILY_API_KEY` | Enables Tavily when `providers.tavily.enabled: true` |
 | `BRAVE_API_KEY` | Enables Brave Search when `providers.brave.enabled: true` |
 | `GROK_API_KEY` | Required only for legacy Grok CLI fallback |
-| `CCS_WEBSEARCH_SKIP` | Skip hook entirely |
-| `CCS_DEBUG` | Verbose hook logging |
+| `CCS_WEBSEARCH_SKIP` | Disable the CCS local WebSearch runtime for the current process |
+| `CCS_DEBUG` | Verbose WebSearch runtime logging |
+
+## Managed Runtime Files
+
+- `~/.claude.json` → CCS manages `mcpServers.ccs-websearch`
+- `~/.ccs/mcp/ccs-websearch-server.cjs` → local MCP server binary
+- `~/.ccs/hooks/websearch-transformer.cjs` → shared provider runtime plus legacy compatibility fallback
 
 ## Troubleshooting
 
@@ -140,7 +153,7 @@ Those providers remain supported, but they are no longer the primary path. Enabl
 1. Check `websearch.enabled: true`
 2. Keep DuckDuckGo enabled unless you have a strong reason to disable it
 3. If using Exa, Tavily, or Brave, verify the matching API key
-4. Run with `CCS_DEBUG=1` for hook logs
+4. Run with `CCS_DEBUG=1` for runtime logs
 
 ## Security Considerations