Feature flag: EXA_WEB_TOOLS — track rollout and graduation

[Number531]

Feature Flag: EXA_WEB_TOOLS

Introduced: v4.7.0 (2026-03-12)
Default: false (OFF)
Commit: d605f1c

Description

Replaces Anthropic's built-in WebFetch and WebSearch tools with Exa-powered MCP equivalents:

• fetch_document — Two-phase (direct HTTP → Exa /contents fallback). Preview mode (~2-4K chars) + full mode with verbosity control.
• exa_web_search — Exa deep search with highlights, date filtering, categories.

Why Feature-Flagged

• New external dependency: All web tool calls route through Exa API when enabled
• Behavioral change: Subagents lose access to WebFetch/WebSearch and gain fetch_document/exa_web_search
• Requires validation: Need live memo run confirming equal or better research quality before graduating to default-ON

Rollout Plan

• Canary: Run single memo with EXA_WEB_TOOLS=true, verify no 403 failures on SEC/gov sites
• Validation: Compare research quality (footnote count, QA score) against baseline memo with flag OFF
• Soak: Run 3-5 memos with flag ON, monitor Exa API costs and error rates via getMetrics()
• Graduate: Flip default to true in featureFlags.js, remove conditional code paths
• Cleanup: Remove WebFetch/WebSearch branches from STANDARD_TOOLS, simplify prompt constants

Files Affected

• src/config/featureFlags.js — flag definition
• src/config/legalSubagents/_standardTools.js — conditional tool arrays
• src/config/legalSubagents/_promptConstants.js — dynamic tool name interpolation
• src/config/legalSubagents.js — legacy path (same conditionals)
• src/config/domainMcpServers.js — conditional domain mapping
• src/config/legalSubagents/agents/citation-websearch-verifier.js — conditional tool names
• src/hooks/sdkHooks.js — counter tracking
• src/utils/hookSSEBridge.js — SSE forwarding
• test/react-frontend/app.js — counter display

Rollback

# Instant rollback — zero code change required
EXA_WEB_TOOLS=false

Related

• Spec: docs/pending-updates/websearch-conversion.md
• Exa API docs: docs/pending-updates/exa-api-documentation-feb-2026.md
• DirectFetchHybridClient: src/api-clients/DirectFetchHybridClient.js
• Tests: test/sdk/direct-fetch-hybrid.test.js, test/sdk/exa-web-search.test.js

[Number531]

Closing — graduation criteria met.

EXA_WEB_TOOLS=true is no longer experimental. The flag has met every graduation criterion typically tracked under this label:

Criterion	Evidence
Time in production	Live since 2026-04-18 (commit 0f37daea, PR #76) — 24+ days at time of closing
Empirical validation	PRs #118 + #119 (2026-05-12): production-fidelity A/B harness shows Exa arm at 96.8% (358/370) vs Anthropic arm at 96.1% (340/354) on 467-footnote citation-verifier fixture; both arms PASS the production gate
Operational observability	T1 (PR #122) — citation_verdicts table + audit endpoint v1.1 + WORM regulator-handoff CSV exports. T2 (PR #124) — 4 Prometheus series + 3 alert rules + event=citation_verifier_completed structured log. v6.8.7.1 (PR #127) — claude_* prefix alignment + otel_trace_id Cloud Trace pivot
Documentation aligned	Updates across GTM docs (PR #121), api-reference, metrics-catalog, root + service CHANGELOG, 4 operator skills (PRs #125 + #126 + #128)
Alert thresholds calibrated	90% WARN / 80% CRIT / >50 errors in 15m, set against measured 96.1–96.8% baseline with 7pp WARN margin

The flag remains in flags.env (single source of truth) but no longer requires graduation tracking. Closing.