@kaitranntt/ccs 7.56.0-dev.4 → 7.56.0-dev.5

package/lib/hooks/websearch-transformer.cjs

@@ -1,51 +1,32 @@
 #!/usr/bin/env node
 /**
- * CCS WebSearch Hook - CLI Tool Executor with Fallback Chain
+ * CCS WebSearch Hook - deterministic search backends with legacy CLI fallback
  *
- * Intercepts Claude's WebSearch tool and executes search via CLI tools.
- * Respects provider enabled states from config.yaml.
- * Supports automatic fallback: Gemini CLI → OpenCode → Grok CLI
+ * Primary providers:
+ *   - Exa Search API
+ *   - Tavily Search API
+ *   - Brave Search API
+ *   - DuckDuckGo HTML search
  *
- * Environment Variables (set by CCS):
- *   CCS_WEBSEARCH_SKIP=1           - Skip this hook entirely (for official Claude)
- *   CCS_WEBSEARCH_ENABLED=1        - Enable WebSearch (default: 1)
- *   CCS_WEBSEARCH_TIMEOUT=55       - Timeout in seconds (default: 55)
- *   CCS_WEBSEARCH_GEMINI=1         - Enable Gemini CLI provider
- *   CCS_WEBSEARCH_GEMINI_MODEL     - Gemini model (default: gemini-2.5-flash)
- *   CCS_WEBSEARCH_OPENCODE=1       - Enable OpenCode provider
- *   CCS_WEBSEARCH_GROK=1           - Enable Grok CLI provider
- *   CCS_WEBSEARCH_OPENCODE_MODEL   - OpenCode model (default: opencode/grok-code)
- *   CCS_DEBUG=1                    - Enable debug output
- *
- * Exit codes:
- *   0 - Allow tool (pass-through to native WebSearch)
- *   2 - Block tool (deny with results/message)
- *
- * @module hooks/websearch-transformer
+ * Legacy compatibility fallback:
+ *   - Gemini CLI
+ *   - OpenCode
+ *   - Grok CLI
  */
 
 const { spawnSync } = require('child_process');
 
-// ============================================================================
-// PLATFORM DETECTION
-// ============================================================================
-
-/**
- * Windows platform flag - used for shell option in spawnSync calls.
- * On Windows, globally installed CLI tools via npm/pnpm are .cmd/.bat files,
- * which require shell: true to execute properly.
- * @see https://github.com/kaitranntt/ccs/issues/378
- */
 const isWindows = process.platform === 'win32';
+const DEFAULT_TIMEOUT_SEC = 55;
+const DEFAULT_RESULT_COUNT = 5;
+const MIN_VALID_RESPONSE_LENGTH = 20;
+const EXA_URL = 'https://api.exa.ai/search';
+const TAVILY_URL = 'https://api.tavily.com/search';
+const DDG_URL = 'https://html.duckduckgo.com/html/';
+const BRAVE_URL = 'https://api.search.brave.com/res/v1/web/search';
+const USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
 
-// ============================================================================
-// CONFIGURATION - Edit these for prompt engineering
-// ============================================================================
-
-/**
- * SHARED INSTRUCTIONS - Applied to ALL providers
- * Edit here to change behavior across all CLI tools at once.
- */
 const SHARED_INSTRUCTIONS = `Instructions:
 1. Search the web for current, up-to-date information
 2. Provide a comprehensive summary of the search results
@@ -55,119 +36,45 @@ const SHARED_INSTRUCTIONS = `Instructions:
 6. If results conflict, note the discrepancy
 7. Format output clearly with sections if the topic is complex`;
 
-/**
- * PROVIDER-SPECIFIC CONFIG - Only tool-use differences and quirks
- * Each provider may have unique capabilities or invocation methods.
- */
 const PROVIDER_CONFIG = {
   gemini: {
-    // Model to use (passed via --model flag)
     model: 'gemini-2.5-flash',
-    // Alternative free models: gemini-2.0-flash, gemini-1.5-flash
-
-    // Provider-specific: How to invoke web search (Gemini has google_web_search tool)
     toolInstruction: 'Use the google_web_search tool to find current information.',
-
-    // Optional quirks (null if none)
     quirks: null,
   },
-
   opencode: {
-    // Model to use (can be overridden via CCS_WEBSEARCH_OPENCODE_MODEL env var)
     model: 'opencode/grok-code',
-    // Alternative models: opencode/gpt-4o, opencode/claude-3.5-sonnet, opencode/gpt-5-nano
-
-    // Provider-specific: OpenCode has built-in web search via Zen
     toolInstruction: 'Search the web using your built-in capabilities.',
-
-    // Optional quirks
     quirks: null,
   },
-
   grok: {
-    // Model to use (Grok CLI uses default model)
     model: 'grok-3',
-    // Note: Grok CLI doesn't support model selection via CLI
-
-    // Provider-specific: Grok has web + X/Twitter search
     toolInstruction: 'Use your web search capabilities to find information.',
-
-    // Grok-specific: Can also search X for real-time info
     quirks: 'For breaking news or real-time events, also check X/Twitter if relevant.',
   },
 };
 
-/**
- * Build the complete prompt for a provider
- * Combines: query + tool instruction + shared instructions + quirks
- */
-function buildPrompt(providerId, query) {
-  const config = PROVIDER_CONFIG[providerId];
-  const parts = [
-    `Search the web for: ${query}`,
-    '',
-    config.toolInstruction,
-    '',
-    SHARED_INSTRUCTIONS,
-  ];
+const ddgLinkRe = /<a[^>]*class="[^"]*result__a[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+const ddgSnippetRe = /<a class="result__snippet[^"]*".*?>([\s\S]*?)<\/a>/g;
+const htmlTagRe = /<[^>]+>/g;
 
-  if (config.quirks) {
-    parts.push('', `Note: ${config.quirks}`);
+function debug(message) {
+  if (process.env.CCS_DEBUG) {
+    console.error(`[CCS Hook] ${message}`);
   }
-
-  return parts.join('\n');
 }
 
-// Minimum response length to consider valid
-const MIN_VALID_RESPONSE_LENGTH = 20;
-
-// Default timeout in seconds
-const DEFAULT_TIMEOUT_SEC = 55;
-
-// ============================================================================
-// HOOK LOGIC - Generally no need to edit below
-// ============================================================================
-
-/**
- * Determine if hook should skip and pass through to native WebSearch.
- * Returns true for native Claude accounts where WebSearch works server-side.
- */
 function shouldSkipHook() {
-  // Explicit skip signal (set by CCS for account profiles)
   if (process.env.CCS_WEBSEARCH_SKIP === '1') return true;
-
-  // Account/default profiles - use native WebSearch
   const profileType = process.env.CCS_PROFILE_TYPE;
   if (profileType === 'account' || profileType === 'default') return true;
-
-  // Explicit disable
   if (process.env.CCS_WEBSEARCH_ENABLED === '0') return true;
-
   return false;
 }
 
-// Read input from stdin
-let input = '';
-process.stdin.setEncoding('utf8');
-process.stdin.on('data', (chunk) => {
-  input += chunk;
-});
-process.stdin.on('end', () => {
-  processHook();
-});
-
-// Handle stdin not being available
-process.stdin.on('error', () => {
-  process.exit(0);
-});
-
-/**
- * Check if a CLI tool is available
- */
 function isCliAvailable(cmd) {
   try {
     const whichCmd = isWindows ? 'where.exe' : 'which';
-
     const result = spawnSync(whichCmd, [cmd], {
       encoding: 'utf8',
       timeout: 2000,
@@ -179,124 +86,330 @@ function isCliAvailable(cmd) {
   }
 }
 
-/**
- * Check if provider is enabled via environment variable
- */
 function isProviderEnabled(provider) {
-  const envVar = `CCS_WEBSEARCH_${provider.toUpperCase()}`;
-  const value = process.env[envVar];
+  return process.env[`CCS_WEBSEARCH_${provider.toUpperCase()}`] === '1';
+}
 
-  // If env var not set, provider is disabled by default
-  // This ensures we respect config.yaml settings
-  return value === '1';
+function hasEnvValue(name) {
+  return (process.env[name] || '').trim().length > 0;
 }
 
-/**
- * Main hook processing logic with fallback chain
- */
-async function processHook() {
-  try {
-    // Skip for native accounts (account, default profiles) or explicit disable
-    if (shouldSkipHook()) {
-      process.exit(0);
+function getFirstEnvValue(names) {
+  for (const name of names) {
+    if (hasEnvValue(name)) {
+      return process.env[name].trim();
     }
+  }
+  return '';
+}
 
-    const data = JSON.parse(input);
+function getProviderApiKey(providerId) {
+  switch (providerId) {
+    case 'brave':
+      return getFirstEnvValue(['BRAVE_API_KEY', 'CCS_WEBSEARCH_BRAVE_API_KEY']);
+    case 'exa':
+      return getFirstEnvValue(['EXA_API_KEY', 'CCS_WEBSEARCH_EXA_API_KEY']);
+    case 'tavily':
+      return getFirstEnvValue(['TAVILY_API_KEY', 'CCS_WEBSEARCH_TAVILY_API_KEY']);
+    default:
+      return '';
+  }
+}
 
-    // Only handle WebSearch tool
-    if (data.tool_name !== 'WebSearch') {
-      process.exit(0);
-    }
+function getResultCount(provider) {
+  const raw = process.env[`CCS_WEBSEARCH_${provider.toUpperCase()}_MAX_RESULTS`];
+  const parsed = Number.parseInt(raw || '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, 10) : DEFAULT_RESULT_COUNT;
+}
 
-    const query = data.tool_input?.query || '';
+function buildPrompt(providerId, query) {
+  const config = PROVIDER_CONFIG[providerId];
+  const parts = [
+    `Search the web for: ${query}`,
+    '',
+    config.toolInstruction,
+    '',
+    SHARED_INSTRUCTIONS,
+  ];
+  if (config.quirks) {
+    parts.push('', `Note: ${config.quirks}`);
+  }
+  return parts.join('\n');
+}
 
-    if (!query) {
-      process.exit(0);
+function decodeHtml(value) {
+  return value
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>');
+}
+
+function compactText(value, maxLength = 280) {
+  const text = String(value || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength - 3).trimEnd()}...`;
+}
+
+function extractDuckDuckGoResults(html, count) {
+  const links = [...html.matchAll(ddgLinkRe)].slice(0, count + 5);
+  const snippets = [...html.matchAll(ddgSnippetRe)].slice(0, count + 5);
+
+  return links.slice(0, count).map((match, index) => {
+    let url = match[1];
+    if (url.includes('uddg=')) {
+      try {
+        const decoded = decodeURIComponent(url);
+        const uddgIndex = decoded.indexOf('uddg=');
+        if (uddgIndex !== -1) {
+          url = decoded.slice(uddgIndex + 5).split('&')[0];
+        }
+      } catch {
+        // keep original url
+      }
     }
 
-    const timeout = parseInt(process.env.CCS_WEBSEARCH_TIMEOUT || DEFAULT_TIMEOUT_SEC, 10);
+    return {
+      title: decodeHtml(match[2].replace(htmlTagRe, '').trim()),
+      url,
+      description: decodeHtml((snippets[index]?.[1] || '').replace(htmlTagRe, '').trim()),
+    };
+  });
+}
 
-    // Fallback chain: Gemini → OpenCode → Grok
-    // Only include providers that are BOTH installed AND enabled in config
-    const providers = [
-      { name: 'Gemini CLI', cmd: 'gemini', id: 'gemini', fn: tryGeminiSearch },
-      { name: 'OpenCode', cmd: 'opencode', id: 'opencode', fn: tryOpenCodeSearch },
-      { name: 'Grok CLI', cmd: 'grok', id: 'grok', fn: tryGrokSearch },
-    ];
+function formatStructuredSearchResults(query, providerName, results) {
+  if (!results.length) {
+    return `No search results found for "${query}" via ${providerName}.`;
+  }
 
-    // Filter to only enabled AND available providers
-    const enabledProviders = providers.filter((p) => {
-      const enabled = isProviderEnabled(p.id);
-      const available = isCliAvailable(p.cmd);
+  const lines = [`Search results for "${query}" via ${providerName}:`, ''];
+  for (const [index, result] of results.entries()) {
+    lines.push(`${index + 1}. ${result.title}`);
+    lines.push(`   ${result.url}`);
+    if (result.description) {
+      lines.push(`   ${result.description}`);
+    }
+    lines.push('');
+  }
+  lines.push('Use these results to answer the user directly.');
+  return lines.join('\n');
+}
 
-      if (process.env.CCS_DEBUG) {
-        console.error(`[CCS Hook] ${p.name}: enabled=${enabled}, available=${available}`);
-      }
+async function fetchWithTimeout(url, options, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
 
-      return enabled && available;
-    });
+async function tryBraveSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  const apiKey = getProviderApiKey('brave');
+  if (!apiKey) {
+    return { success: false, error: 'BRAVE_API_KEY is not set' };
+  }
 
-    const errors = [];
+  const params = new URLSearchParams({
+    q: query,
+    count: String(getResultCount('brave')),
+  });
 
-    if (process.env.CCS_DEBUG) {
-      const names = enabledProviders.map((p) => p.name).join(', ') || 'none';
-      console.error(`[CCS Hook] Enabled providers: ${names}`);
+  try {
+    const response = await fetchWithTimeout(
+      `${BRAVE_URL}?${params.toString()}`,
+      {
+        headers: {
+          Accept: 'application/json',
+          'User-Agent': USER_AGENT,
+          'X-Subscription-Token': apiKey,
+        },
+      },
+      timeoutSec * 1000
+    );
+
+    if (!response.ok) {
+      const body = await response.text();
+      return {
+        success: false,
+        error: `Brave Search returned ${response.status}: ${body.slice(0, 160)}`,
+      };
     }
 
-    // Try each enabled provider in order
-    for (const provider of enabledProviders) {
-      if (process.env.CCS_DEBUG) {
-        console.error(`[CCS Hook] Trying ${provider.name}...`);
-      }
-
-      const result = provider.fn(query, timeout);
+    const body = await response.json();
+    const results = (body.web?.results || []).map((result) => ({
+      title: result.title || 'Untitled',
+      url: result.url || '',
+      description: result.description || '',
+    }));
 
-      if (result.success) {
-        outputSuccess(query, result.content, provider.name);
-        return;
-      }
+    return {
+      success: true,
+      content: formatStructuredSearchResults(query, 'Brave Search', results),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.name === 'AbortError' ? 'Brave Search timed out' : error.message,
+    };
+  }
+}
 
-      if (process.env.CCS_DEBUG) {
-        console.error(`[CCS Hook] ${provider.name} failed: ${result.error}`);
-      }
+async function tryExaSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  const apiKey = getProviderApiKey('exa');
+  if (!apiKey) {
+    return { success: false, error: 'EXA_API_KEY is not set' };
+  }
 
-      errors.push({ provider: provider.name, error: result.error });
+  try {
+    const response = await fetchWithTimeout(
+      EXA_URL,
+      {
+        method: 'POST',
+        headers: {
+          Accept: 'application/json',
+          'Content-Type': 'application/json',
+          'User-Agent': USER_AGENT,
+          'x-api-key': apiKey,
+        },
+        body: JSON.stringify({
+          query,
+          type: 'auto',
+          numResults: getResultCount('exa'),
+          text: true,
+        }),
+      },
+      timeoutSec * 1000
+    );
+
+    if (!response.ok) {
+      const body = await response.text();
+      return { success: false, error: `Exa returned ${response.status}: ${body.slice(0, 160)}` };
     }
 
-    // All providers failed or none enabled
-    if (enabledProviders.length === 0) {
-      // No providers enabled - pass through to native WebSearch
-      // This allows native Claude accounts to use server-side WebSearch
-      process.exit(0);
-    } else {
-      outputAllFailedMessage(query, errors);
+    const body = await response.json();
+    const results = (body.results || []).map((result) => ({
+      title: compactText(result.title || result.url || 'Untitled', 120),
+      url: result.url || '',
+      description: compactText(result.text || result.summary || '', 240),
+    }));
+
+    return {
+      success: true,
+      content: formatStructuredSearchResults(query, 'Exa', results),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.name === 'AbortError' ? 'Exa timed out' : error.message,
+    };
+  }
+}
+
+async function tryTavilySearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  const apiKey = getProviderApiKey('tavily');
+  if (!apiKey) {
+    return { success: false, error: 'TAVILY_API_KEY is not set' };
+  }
+
+  try {
+    const response = await fetchWithTimeout(
+      TAVILY_URL,
+      {
+        method: 'POST',
+        headers: {
+          Accept: 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+          'Content-Type': 'application/json',
+          'User-Agent': USER_AGENT,
+        },
+        body: JSON.stringify({
+          query,
+          search_depth: 'basic',
+          max_results: getResultCount('tavily'),
+          include_answer: false,
+          include_raw_content: false,
+        }),
+      },
+      timeoutSec * 1000
+    );
+
+    if (!response.ok) {
+      const body = await response.text();
+      return { success: false, error: `Tavily returned ${response.status}: ${body.slice(0, 160)}` };
     }
-  } catch (err) {
-    if (process.env.CCS_DEBUG) {
-      console.error('[CCS Hook] Parse error:', err.message);
+
+    const body = await response.json();
+    const results = (body.results || []).map((result) => ({
+      title: compactText(result.title || result.url || 'Untitled', 120),
+      url: result.url || '',
+      description: compactText(result.content || '', 240),
+    }));
+
+    return {
+      success: true,
+      content: formatStructuredSearchResults(query, 'Tavily', results),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.name === 'AbortError' ? 'Tavily timed out' : error.message,
+    };
+  }
+}
+
+async function tryDuckDuckGoSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
+  try {
+    const params = new URLSearchParams({ q: query });
+    const response = await fetchWithTimeout(
+      `${DDG_URL}?${params.toString()}`,
+      {
+        headers: {
+          Accept: 'text/html',
+          'User-Agent': USER_AGENT,
+        },
+      },
+      timeoutSec * 1000
+    );
+
+    if (!response.ok) {
+      return { success: false, error: `DuckDuckGo returned ${response.status}` };
     }
-    process.exit(0);
+
+    const html = await response.text();
+    const results = extractDuckDuckGoResults(html, getResultCount('duckduckgo'));
+    return {
+      success: true,
+      content: formatStructuredSearchResults(query, 'DuckDuckGo', results),
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.name === 'AbortError' ? 'DuckDuckGo timed out' : error.message,
+    };
   }
 }
 
-/**
- * Execute search via Gemini CLI
- */
 function shouldRetryGeminiWithLegacyPrompt(errorMessage) {
-  const lowerError = (errorMessage || '').toLowerCase();
-
+  const lower = (errorMessage || '').toLowerCase();
   return (
-    lowerError.includes('unknown option') ||
-    lowerError.includes('unknown argument') ||
-    lowerError.includes('unrecognized option') ||
-    lowerError.includes('usage: gemini') ||
-    lowerError.includes('use --prompt') ||
-    lowerError.includes('using the --prompt option')
+    lower.includes('unknown option') ||
+    lower.includes('unknown argument') ||
+    lower.includes('unrecognized option') ||
+    lower.includes('usage: gemini') ||
+    lower.includes('use --prompt') ||
+    lower.includes('using the --prompt option')
   );
 }
 
 function runGeminiCommand(args, timeoutMs) {
-  const spawnResult = spawnSync('gemini', args, {
+  const result = spawnSync('gemini', args, {
     encoding: 'utf8',
     timeout: timeoutMs,
     maxBuffer: 1024 * 1024 * 2,
@@ -304,241 +417,130 @@ function runGeminiCommand(args, timeoutMs) {
     shell: isWindows,
   });
 
-  if (spawnResult.error) {
-    if (spawnResult.error.code === 'ENOENT') {
+  if (result.error) {
+    if (result.error.code === 'ENOENT')
       return { success: false, error: 'Gemini CLI not installed' };
-    }
-    throw spawnResult.error;
+    throw result.error;
   }
-
-  if (spawnResult.status !== 0) {
-    const stderr = (spawnResult.stderr || '').trim();
+  if (result.status !== 0) {
     return {
       success: false,
-      error: stderr || `Gemini CLI exited with code ${spawnResult.status}`,
+      error: (result.stderr || '').trim() || `Gemini CLI exited with code ${result.status}`,
     };
   }
 
-  const result = (spawnResult.stdout || '').trim();
-
-  if (!result || result.length < MIN_VALID_RESPONSE_LENGTH) {
+  const output = (result.stdout || '').trim();
+  if (!output || output.length < MIN_VALID_RESPONSE_LENGTH) {
     return { success: false, error: 'Empty or too short response from Gemini' };
   }
-
-  const lowerResult = result.toLowerCase();
-  if (
-    lowerResult.includes('error:') ||
-    lowerResult.includes('failed to') ||
-    lowerResult.includes('authentication required')
-  ) {
-    return { success: false, error: `Gemini returned error: ${result.substring(0, 100)}` };
-  }
-
-  return { success: true, content: result };
+  return { success: true, content: output };
 }
 
 function tryGeminiSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
   try {
     const timeoutMs = timeoutSec * 1000;
-    const config = PROVIDER_CONFIG.gemini;
+    const model = process.env.CCS_WEBSEARCH_GEMINI_MODEL || PROVIDER_CONFIG.gemini.model;
     const prompt = buildPrompt('gemini', query);
-
-    // Allow model override via env var
-    const model = process.env.CCS_WEBSEARCH_GEMINI_MODEL || config.model;
     const baseArgs = ['--model', model, '--yolo'];
-    const positionalArgs = [...baseArgs, prompt];
-
-    if (process.env.CCS_DEBUG) {
-      console.error(`[CCS Hook] Executing: gemini --model ${model} --yolo "..."`);
-    }
 
-    // Current Gemini CLI prefers positional prompts and deprecates -p/--prompt.
-    // Retry once with -p for legacy CLIs that still require it.
-    const positionalResult = runGeminiCommand(positionalArgs, timeoutMs);
-    if (positionalResult.success) {
+    debug(`Executing Gemini legacy fallback with model ${model}`);
+    const positionalResult = runGeminiCommand([...baseArgs, prompt], timeoutMs);
+    if (positionalResult.success || !shouldRetryGeminiWithLegacyPrompt(positionalResult.error)) {
       return positionalResult;
     }
 
-    if (!shouldRetryGeminiWithLegacyPrompt(positionalResult.error)) {
-      return positionalResult;
-    }
-
-    if (process.env.CCS_DEBUG) {
-      console.error('[CCS Hook] Positional Gemini prompt failed; retrying with -p for legacy CLI');
-      console.error(`[CCS Hook] Executing: gemini --model ${model} --yolo -p "..."`);
-    }
-
-    const legacyPromptArgs = [...baseArgs, '-p', prompt];
-    return runGeminiCommand(legacyPromptArgs, timeoutMs);
-  } catch (err) {
-    if (err.killed) {
-      return { success: false, error: 'Gemini CLI timed out' };
-    }
-    return { success: false, error: err.message || 'Unknown Gemini error' };
+    return runGeminiCommand([...baseArgs, '-p', prompt], timeoutMs);
+  } catch (error) {
+    return {
+      success: false,
+      error: error.killed ? 'Gemini CLI timed out' : error.message || 'Unknown Gemini error',
+    };
   }
 }
 
-/**
- * Execute search via OpenCode CLI
- */
 function tryOpenCodeSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
   try {
-    const timeoutMs = timeoutSec * 1000;
-    const config = PROVIDER_CONFIG.opencode;
-
-    // Allow model override via env var
-    const model = process.env.CCS_WEBSEARCH_OPENCODE_MODEL || config.model;
-    const prompt = buildPrompt('opencode', query);
-
-    if (process.env.CCS_DEBUG) {
-      console.error(`[CCS Hook] Executing: opencode run --model ${model} "..."`);
-    }
-
-    const spawnResult = spawnSync('opencode', ['run', prompt, '--model', model], {
-      encoding: 'utf8',
-      timeout: timeoutMs,
-      maxBuffer: 1024 * 1024 * 2,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      shell: isWindows,
-    });
+    const model = process.env.CCS_WEBSEARCH_OPENCODE_MODEL || PROVIDER_CONFIG.opencode.model;
+    const result = spawnSync(
+      'opencode',
+      ['run', buildPrompt('opencode', query), '--model', model],
+      {
+        encoding: 'utf8',
+        timeout: timeoutSec * 1000,
+        maxBuffer: 1024 * 1024 * 2,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        shell: isWindows,
+      }
+    );
 
-    if (spawnResult.error) {
-      if (spawnResult.error.code === 'ENOENT') {
+    if (result.error) {
+      if (result.error.code === 'ENOENT')
         return { success: false, error: 'OpenCode not installed' };
-      }
-      throw spawnResult.error;
+      throw result.error;
     }
-
-    if (spawnResult.status !== 0) {
-      const stderr = (spawnResult.stderr || '').trim();
+    if (result.status !== 0) {
       return {
         success: false,
-        error: stderr || `OpenCode exited with code ${spawnResult.status}`,
+        error: (result.stderr || '').trim() || `OpenCode exited with code ${result.status}`,
       };
     }
 
-    const result = (spawnResult.stdout || '').trim();
-
-    if (!result || result.length < MIN_VALID_RESPONSE_LENGTH) {
+    const output = (result.stdout || '').trim();
+    if (!output || output.length < MIN_VALID_RESPONSE_LENGTH) {
       return { success: false, error: 'Empty or too short response from OpenCode' };
     }
-
-    const lowerResult = result.toLowerCase();
-    if (
-      lowerResult.includes('error:') ||
-      lowerResult.includes('failed to') ||
-      lowerResult.includes('authentication required')
-    ) {
-      return { success: false, error: `OpenCode returned error: ${result.substring(0, 100)}` };
-    }
-
-    return { success: true, content: result };
-  } catch (err) {
-    if (err.killed) {
-      return { success: false, error: 'OpenCode timed out' };
-    }
-    return { success: false, error: err.message || 'Unknown OpenCode error' };
+    return { success: true, content: output };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.killed ? 'OpenCode timed out' : error.message || 'Unknown OpenCode error',
+    };
   }
 }
 
-/**
- * Execute search via Grok CLI
- */
 function tryGrokSearch(query, timeoutSec = DEFAULT_TIMEOUT_SEC) {
   try {
-    const timeoutMs = timeoutSec * 1000;
-    const prompt = buildPrompt('grok', query);
-
-    if (process.env.CCS_DEBUG) {
-      console.error('[CCS Hook] Executing: grok "..."');
-    }
-
-    const spawnResult = spawnSync('grok', [prompt], {
+    const result = spawnSync('grok', [buildPrompt('grok', query)], {
       encoding: 'utf8',
-      timeout: timeoutMs,
+      timeout: timeoutSec * 1000,
       maxBuffer: 1024 * 1024 * 2,
       stdio: ['pipe', 'pipe', 'pipe'],
       shell: isWindows,
     });
 
-    if (spawnResult.error) {
-      if (spawnResult.error.code === 'ENOENT') {
+    if (result.error) {
+      if (result.error.code === 'ENOENT')
         return { success: false, error: 'Grok CLI not installed' };
-      }
-      throw spawnResult.error;
+      throw result.error;
     }
-
-    if (spawnResult.status !== 0) {
-      const stderr = (spawnResult.stderr || '').trim();
+    if (result.status !== 0) {
       return {
         success: false,
-        error: stderr || `Grok CLI exited with code ${spawnResult.status}`,
+        error: (result.stderr || '').trim() || `Grok CLI exited with code ${result.status}`,
       };
     }
 
-    const result = (spawnResult.stdout || '').trim();
-
-    if (!result || result.length < MIN_VALID_RESPONSE_LENGTH) {
+    const output = (result.stdout || '').trim();
+    if (!output || output.length < MIN_VALID_RESPONSE_LENGTH) {
       return { success: false, error: 'Empty or too short response from Grok' };
     }
-
-    const lowerResult = result.toLowerCase();
-    if (
-      lowerResult.includes('error:') ||
-      lowerResult.includes('failed to') ||
-      lowerResult.includes('api key')
-    ) {
-      return { success: false, error: `Grok returned error: ${result.substring(0, 100)}` };
-    }
-
-    return { success: true, content: result };
-  } catch (err) {
-    if (err.killed) {
-      return { success: false, error: 'Grok CLI timed out' };
-    }
-    return { success: false, error: err.message || 'Unknown Grok error' };
+    return { success: true, content: output };
+  } catch (error) {
+    return {
+      success: false,
+      error: error.killed ? 'Grok CLI timed out' : error.message || 'Unknown Grok error',
+    };
   }
 }
 
-/**
- * Format search results for Claude
- */
-function formatSearchResults(query, content, providerName) {
-  return [
-    `[WebSearch Result via ${providerName}]`,
-    '',
-    `Query: "${query}"`,
-    '',
-    content,
-    '',
-    '---',
-    'Use this information to answer the user.',
-  ].join('\n');
-}
-
-/**
- * Output success response and exit
- *
- * Key insight from Claude Code docs:
- * - permissionDecisionReason (with deny) → shown to CLAUDE (AI reads this)
- * - systemMessage → shown to USER only (nice styling but AI doesn't see)
- *
- * So we MUST put results in permissionDecisionReason for Claude to use them.
- * systemMessage provides the nice UI for the user.
- */
 function outputSuccess(query, content, providerName) {
-  const formattedResults = formatSearchResults(query, content, providerName);
-
   const output = {
     decision: 'block',
-    reason: `WebSearch completed via ${providerName}`,
-    // Nice message for user (shows as "says:" - info style)
-    systemMessage: `[WebSearch via ${providerName}] Results retrieved successfully. See below.`,
+    reason: `WebSearch handled via ${providerName}`,
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
       permissionDecision: 'deny',
-      // Full results here - Claude reads this
-      permissionDecisionReason: formattedResults,
+      permissionDecisionReason: `[WebSearch Result via ${providerName}]\n\nQuery: "${query}"\n\n${content}`,
     },
   };
 
@@ -546,29 +548,15 @@ function outputSuccess(query, content, providerName) {
   process.exit(2);
 }
 
-/**
- * Output error message
- */
-function outputError(query, error, providerName) {
-  const message = [
-    `[WebSearch - ${providerName} Error]`,
-    '',
-    `Error: ${error}`,
-    '',
-    `Query: "${query}"`,
-    '',
-    'Troubleshooting:',
-    '  - Check ~/.gemini/oauth_creds.json exists',
-    '  - Re-authenticate: run `gemini` (opens browser)',
-  ].join('\n');
-
+function outputAllFailedMessage(query, errors) {
+  const detail = errors.map((entry) => `${entry.provider}: ${entry.error}`).join(' | ');
   const output = {
     decision: 'block',
-    reason: `WebSearch failed: ${error}`,
+    reason: 'WebSearch fallback failed',
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
       permissionDecision: 'deny',
-      permissionDecisionReason: message,
+      permissionDecisionReason: `WebSearch could not be completed for "${query}". ${detail}`,
     },
   };
 
@@ -576,83 +564,121 @@ function outputError(query, error, providerName) {
   process.exit(2);
 }
 
-/**
- * Output no providers enabled message
- */
-function outputNoProvidersEnabled(query) {
-  const message = [
-    '[WebSearch - No Providers Enabled]',
-    '',
-    'No WebSearch providers are enabled in config.',
-    '',
-    'To enable: Run `ccs config` and enable a provider.',
-    '',
-    'Or install one of the following CLI tools:',
-    '',
-    '1. Gemini CLI (FREE, 1000 req/day):',
-    '   npm install -g @google/gemini-cli',
-    '   gemini  # opens browser to authenticate',
-    '',
-    '2. OpenCode (FREE via Zen):',
-    '   curl -fsSL https://opencode.ai/install | bash',
-    '',
-    '3. Grok CLI (requires XAI_API_KEY):',
-    '   npm install -g @vibe-kit/grok-cli',
-    '',
-    `Query: "${query}"`,
-  ].join('\n');
+async function processHook(input) {
+  try {
+    if (shouldSkipHook()) {
+      process.exit(0);
+    }
 
-  const output = {
-    decision: 'block',
-    reason: 'WebSearch unavailable - no providers enabled',
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: message,
-    },
-  };
+    const data = JSON.parse(input);
+    if (data.tool_name !== 'WebSearch') {
+      process.exit(0);
+    }
 
-  console.log(JSON.stringify(output));
-  process.exit(2);
-}
+    const query = data.tool_input?.query || '';
+    if (!query) {
+      process.exit(0);
+    }
 
-/**
- * Output no tools message (legacy - kept for backwards compatibility)
- */
-function outputNoToolsMessage(query) {
-  outputNoProvidersEnabled(query);
-}
+    const timeout = Number.parseInt(
+      process.env.CCS_WEBSEARCH_TIMEOUT || `${DEFAULT_TIMEOUT_SEC}`,
+      10
+    );
+    const providers = [
+      {
+        name: 'Exa',
+        id: 'exa',
+        available: () => isProviderEnabled('exa') && Boolean(getProviderApiKey('exa')),
+        fn: tryExaSearch,
+      },
+      {
+        name: 'Tavily',
+        id: 'tavily',
+        available: () => isProviderEnabled('tavily') && Boolean(getProviderApiKey('tavily')),
+        fn: tryTavilySearch,
+      },
+      {
+        name: 'Brave Search',
+        id: 'brave',
+        available: () => isProviderEnabled('brave') && Boolean(getProviderApiKey('brave')),
+        fn: tryBraveSearch,
+      },
+      {
+        name: 'DuckDuckGo',
+        id: 'duckduckgo',
+        available: () => isProviderEnabled('duckduckgo'),
+        fn: tryDuckDuckGoSearch,
+      },
+      {
+        name: 'Gemini CLI',
+        id: 'gemini',
+        available: () => isProviderEnabled('gemini') && isCliAvailable('gemini'),
+        fn: tryGeminiSearch,
+      },
+      {
+        name: 'OpenCode',
+        id: 'opencode',
+        available: () => isProviderEnabled('opencode') && isCliAvailable('opencode'),
+        fn: tryOpenCodeSearch,
+      },
+      {
+        name: 'Grok CLI',
+        id: 'grok',
+        available: () => isProviderEnabled('grok') && isCliAvailable('grok'),
+        fn: tryGrokSearch,
+      },
+    ];
 
-/**
- * Output all providers failed message
- */
-function outputAllFailedMessage(query, errors) {
-  const errorDetails = errors.map((e) => `  - ${e.provider}: ${e.error}`).join('\n');
+    const activeProviders = providers.filter((provider) => provider.available());
+    debug(
+      `Enabled providers: ${activeProviders.map((provider) => provider.name).join(', ') || 'none'}`
+    );
 
-  const message = [
-    '[WebSearch - All Providers Failed]',
-    '',
-    'Tried all enabled CLI tools but all failed:',
-    errorDetails,
-    '',
-    `Query: "${query}"`,
-    '',
-    'Troubleshooting:',
-    '  - Gemini: run `gemini` to authenticate (opens browser)',
-    '  - OpenCode: opencode --version',
-    '  - Grok: Check XAI_API_KEY environment variable',
-  ].join('\n');
+    if (activeProviders.length === 0) {
+      process.exit(0);
+    }
 
-  const output = {
-    decision: 'block',
-    reason: 'WebSearch failed - all providers failed',
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: message,
-    },
-  };
+    const errors = [];
+    for (const provider of activeProviders) {
+      debug(`Trying ${provider.name}`);
+      const result = await provider.fn(query, timeout);
+      if (result.success) {
+        outputSuccess(query, result.content, provider.name);
+        return;
+      }
+      errors.push({ provider: provider.name, error: result.error });
+    }
 
-  console.log(JSON.stringify(output));
-  process.exit(2);
+    outputAllFailedMessage(query, errors);
+  } catch (error) {
+    debug(`Hook error: ${error.message}`);
+    process.exit(0);
+  }
 }
+
+function startFromStdin() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    input += chunk;
+  });
+  process.stdin.on('end', () => {
+    processHook(input);
+  });
+  process.stdin.on('error', () => {
+    process.exit(0);
+  });
+}
+
+if (require.main === module) {
+  startFromStdin();
+}
+
+module.exports = {
+  extractDuckDuckGoResults,
+  formatStructuredSearchResults,
+  tryExaSearch,
+  tryTavilySearch,
+  tryDuckDuckGoSearch,
+  tryBraveSearch,
+};