pi-web-providers 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,4 +1,7 @@
 // src/index.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join as join4 } from "node:path";
 import {
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
@@ -6,33 +9,31 @@ import {
   keyHint,
   truncateHead
 } from "@mariozechner/pi-coding-agent";
-import { StringEnum } from "@mariozechner/pi-ai";
 import {
   Editor,
-  Key,
-  Text,
   getEditorKeybindings,
+  Key,
   matchesKey,
+  Text,
   truncateToWidth,
   visibleWidth,
   wrapTextWithAnsi
 } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
-import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join as join2 } from "node:path";
 
 // src/config.ts
-import { getAgentDir } from "@mariozechner/pi-coding-agent";
 import { execSync } from "node:child_process";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
 
 // src/provider-tools.ts
 var PROVIDER_TOOLS = {
+  claude: ["search", "answer"],
   codex: ["search"],
   exa: ["search", "contents", "answer", "research"],
-  gemini: ["search", "answer", "research"],
+  gemini: ["search", "contents", "answer", "research"],
+  perplexity: ["search", "answer", "research"],
   parallel: ["search", "contents"],
   valyu: ["search", "contents", "answer", "research"]
 };
@@ -76,6 +77,7 @@ var LEGACY_TOOL_ALIASES = {
 };
 var CONFIG_FILE_NAME = "web-providers.json";
 var VERSION = 1;
+var commandValueCache = /* @__PURE__ */ new Map();
 function getConfigPath() {
   return join(getAgentDir(), CONFIG_FILE_NAME);
 }
@@ -115,11 +117,26 @@ function serializeConfig(config) {
 function resolveConfigValue(reference) {
   if (!reference) return void 0;
   if (reference.startsWith("!")) {
-    const output = execSync(reference.slice(1), {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "pipe"]
-    }).trim();
-    return output.length > 0 ? output : void 0;
+    const cached = commandValueCache.get(reference);
+    if (cached) {
+      if (cached.errorMessage) {
+        throw new Error(cached.errorMessage);
+      }
+      return cached.value;
+    }
+    try {
+      const output = execSync(reference.slice(1), {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"]
+      }).trim();
+      const value = output.length > 0 ? output : void 0;
+      commandValueCache.set(reference, { value });
+      return value;
+    } catch (error) {
+      const errorMessage = error.message;
+      commandValueCache.set(reference, { errorMessage });
+      throw error;
+    }
   }
   const envValue = process.env[reference];
   if (envValue !== void 0) {
@@ -158,6 +175,12 @@ function normalizeConfig(raw, source) {
       throw new Error(`'providers' in ${source} must be a JSON object.`);
     }
     config.providers = {};
+    if (raw.providers.claude !== void 0) {
+      config.providers.claude = normalizeClaudeProvider(
+        raw.providers.claude,
+        source
+      );
+    }
     if (raw.providers.codex !== void 0) {
       config.providers.codex = normalizeCodexProvider(
         raw.providers.codex,
@@ -173,6 +196,12 @@ function normalizeConfig(raw, source) {
         source
       );
     }
+    if (raw.providers.perplexity !== void 0) {
+      config.providers.perplexity = normalizePerplexityProvider(
+        raw.providers.perplexity,
+        source
+      );
+    }
     if (raw.providers.parallel !== void 0) {
       config.providers.parallel = normalizeParallelProvider(
         raw.providers.parallel,
@@ -186,7 +215,7 @@ function normalizeConfig(raw, source) {
       );
     }
     const unknownProviders = Object.keys(raw.providers).filter(
-      (key) => key !== "codex" && key !== "exa" && key !== "gemini" && key !== "parallel" && key !== "valyu"
+      (key) => key !== "claude" && key !== "codex" && key !== "exa" && key !== "gemini" && key !== "perplexity" && key !== "parallel" && key !== "valyu"
     );
     if (unknownProviders.length > 0) {
       throw new Error(
@@ -196,6 +225,50 @@ function normalizeConfig(raw, source) {
   }
   return config;
 }
+function normalizeClaudeProvider(raw, source) {
+  const provider = parseProviderObject(raw, source, "claude");
+  const defaults = parseOptionalJsonObject(
+    provider.defaults,
+    source,
+    "providers.claude.defaults"
+  );
+  return {
+    enabled: parseOptionalBoolean(
+      provider.enabled,
+      source,
+      "providers.claude.enabled"
+    ),
+    tools: parseOptionalProviderTools(
+      "claude",
+      provider.tools,
+      source,
+      "providers.claude.tools"
+    ),
+    pathToClaudeCodeExecutable: parseOptionalString(
+      provider.pathToClaudeCodeExecutable,
+      source,
+      "providers.claude.pathToClaudeCodeExecutable"
+    ),
+    defaults: defaults === void 0 ? void 0 : {
+      model: parseOptionalString(
+        defaults.model,
+        source,
+        "providers.claude.defaults.model"
+      ),
+      effort: parseOptionalLiteral(
+        defaults.effort,
+        source,
+        "providers.claude.defaults.effort",
+        ["low", "medium", "high", "max"]
+      ),
+      maxTurns: parseOptionalInteger(
+        defaults.maxTurns,
+        source,
+        "providers.claude.defaults.maxTurns"
+      )
+    }
+  };
+}
 function normalizeCodexProvider(raw, source) {
   const provider = parseProviderObject(raw, source, "codex");
   const defaults = parseOptionalJsonObject(
@@ -369,6 +442,11 @@ function normalizeGeminiProvider(raw, source) {
         source,
         "providers.gemini.defaults.searchModel"
       ),
+      contentsModel: parseOptionalString(
+        defaults.contentsModel,
+        source,
+        "providers.gemini.defaults.contentsModel"
+      ),
       answerModel: parseOptionalString(
         defaults.answerModel,
         source,
@@ -382,6 +460,54 @@ function normalizeGeminiProvider(raw, source) {
     }
   };
 }
+function normalizePerplexityProvider(raw, source) {
+  const provider = parseProviderObject(raw, source, "perplexity");
+  const defaults = parseOptionalJsonObject(
+    provider.defaults,
+    source,
+    "providers.perplexity.defaults"
+  );
+  return {
+    enabled: parseOptionalBoolean(
+      provider.enabled,
+      source,
+      "providers.perplexity.enabled"
+    ),
+    tools: parseOptionalProviderTools(
+      "perplexity",
+      provider.tools,
+      source,
+      "providers.perplexity.tools"
+    ),
+    apiKey: parseOptionalString(
+      provider.apiKey,
+      source,
+      "providers.perplexity.apiKey"
+    ),
+    baseUrl: parseOptionalString(
+      provider.baseUrl,
+      source,
+      "providers.perplexity.baseUrl"
+    ),
+    defaults: defaults === void 0 ? void 0 : {
+      search: parseOptionalJsonObject(
+        defaults.search,
+        source,
+        "providers.perplexity.defaults.search"
+      ),
+      answer: parseOptionalJsonObject(
+        defaults.answer,
+        source,
+        "providers.perplexity.defaults.answer"
+      ),
+      research: parseOptionalJsonObject(
+        defaults.research,
+        source,
+        "providers.perplexity.defaults.research"
+      )
+    }
+  };
+}
 function normalizeParallelProvider(raw, source) {
   const provider = parseProviderObject(raw, source, "parallel");
   const defaults = parseOptionalJsonObject(
@@ -450,18 +576,14 @@ function parseOptionalProviderTools(providerId, value, source, field) {
       continue;
     }
     if (!supportsProviderTool(providerId, normalizedKey)) {
-      throw new Error(
-        `Unknown tools for ${providerId} in ${source}: ${key}.`
-      );
+      throw new Error(`Unknown tools for ${providerId} in ${source}: ${key}.`);
     }
     parsed[normalizedKey] = parseBoolean(entry, source, `${field}.${key}`);
   }
-  const unknownTools = Object.keys(value).filter(
-    (toolId) => {
-      const normalizedKey = normalizeProviderToolKey(providerId, toolId);
-      return normalizedKey !== null && !PROVIDER_TOOLS[providerId].includes(normalizedKey);
-    }
-  );
+  const unknownTools = Object.keys(value).filter((toolId) => {
+    const normalizedKey = normalizeProviderToolKey(providerId, toolId);
+    return normalizedKey !== null && !PROVIDER_TOOLS[providerId].includes(normalizedKey);
+  });
   if (unknownTools.length > 0) {
     throw new Error(
       `Unknown tools for ${providerId} in ${source}: ${unknownTools.join(", ")}.`
@@ -522,6 +644,13 @@ function parseString(value, source, field) {
   }
   return value;
 }
+function parseOptionalInteger(value, source, field) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    throw new Error(`'${field}' in ${source} must be a positive integer.`);
+  }
+  return value;
+}
 function parseOptionalLiteral(value, source, field, allowed) {
   if (value === void 0) return void 0;
   if (typeof value !== "string" || !allowed.includes(value)) {
@@ -535,8 +664,14 @@ function isPlainObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-// src/providers/codex.ts
-import { Codex } from "@openai/codex-sdk";
+// src/providers/claude.ts
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname as dirname2, extname, join as join2 } from "node:path";
+import {
+  query
+} from "@anthropic-ai/claude-agent-sdk";
 
 // src/providers/shared.ts
 function trimSnippet(input, maxLength = 300) {
@@ -551,8 +686,9 @@ function formatJson(value) {
   return JSON.stringify(value, null, 2);
 }
 
-// src/providers/codex.ts
-var OUTPUT_SCHEMA = {
+// src/providers/claude.ts
+var require2 = createRequire(import.meta.url);
+var SEARCH_OUTPUT_SCHEMA = {
   type: "object",
   additionalProperties: false,
   properties: {
@@ -572,20 +708,36 @@ var OUTPUT_SCHEMA = {
   },
   required: ["sources"]
 };
-var CodexProvider = class {
-  id = "codex";
-  label = "Codex";
-  docsUrl = "https://github.com/openai/codex/tree/main/sdk/typescript";
+var ANSWER_OUTPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    answer: { type: "string" },
+    sources: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          title: { type: "string" },
+          url: { type: "string" }
+        },
+        required: ["title", "url"]
+      }
+    }
+  },
+  required: ["answer", "sources"]
+};
+var ClaudeProvider = class {
+  id = "claude";
+  label = "Claude";
+  docsUrl = "https://github.com/anthropics/claude-agent-sdk-typescript";
   createTemplate() {
     return {
-      enabled: true,
+      enabled: false,
       tools: {
-        search: true
-      },
-      defaults: {
-        networkAccessEnabled: true,
-        webSearchEnabled: true,
-        webSearchMode: "live"
+        search: true,
+        answer: true
       }
     };
   }
@@ -596,103 +748,555 @@ var CodexProvider = class {
     if (config.enabled === false) {
       return { available: false, summary: "disabled" };
     }
+    const executablePath = resolveClaudeExecutablePath(config);
+    if (executablePath && !existsSync(executablePath)) {
+      return { available: false, summary: "missing Claude Code executable" };
+    }
+    const authStatus = getClaudeAuthStatus(executablePath);
+    if (!authStatus.loggedIn) {
+      return { available: false, summary: "missing Claude auth" };
+    }
     return { available: true, summary: "enabled" };
   }
-  async search(query, maxResults, config, context) {
-    const codex = new Codex({
-      codexPathOverride: config.codexPath,
-      baseUrl: config.baseUrl,
-      apiKey: resolveConfigValue(config.apiKey),
-      config: config.config,
-      env: resolveEnvMap(config.env)
-    });
-    const thread = codex.startThread({
-      additionalDirectories: config.defaults?.additionalDirectories,
-      approvalPolicy: "never",
-      model: config.defaults?.model,
-      modelReasoningEffort: config.defaults?.modelReasoningEffort,
-      networkAccessEnabled: config.defaults?.networkAccessEnabled ?? true,
-      sandboxMode: "read-only",
-      skipGitRepoCheck: true,
-      webSearchEnabled: config.defaults?.webSearchEnabled ?? true,
-      webSearchMode: config.defaults?.webSearchMode ?? "live",
-      workingDirectory: context.cwd
-    });
-    const prompt = [
-      "You are performing web research for another coding agent.",
-      "Search the public web and return only a JSON object matching the provided schema.",
-      "Do not include markdown fences or extra commentary.",
-      `Return at most ${maxResults} sources.`,
-      "Prefer primary or official sources when they are available.",
-      "Each snippet should be short and specific.",
-      "",
-      `User query: ${query}`
-    ].join("\n");
-    const streamed = await thread.runStreamed(prompt, {
-      outputSchema: OUTPUT_SCHEMA,
-      signal: context.signal
-    });
-    let finalResponse = "";
-    const seenQueries = /* @__PURE__ */ new Set();
-    for await (const event of streamed.events) {
-      handleProgressEvent(event, seenQueries, context.onProgress);
-      if (event.type === "item.completed" && event.item.type === "agent_message") {
-        finalResponse = event.item.text;
-      }
-      if (event.type === "turn.failed") {
-        throw new Error(event.error.message);
-      }
-    }
-    const parsed = parseOutput(finalResponse);
+  async search(queryText, maxResults, options, config, context) {
+    const output = parseClaudeSearchOutput(
+      await this.runStructuredQuery({
+        prompt: [
+          "You are performing web research for another coding agent.",
+          "Use the WebSearch tool to search the public web.",
+          "Return only a JSON object matching the provided schema.",
+          "Do not include markdown fences or extra commentary.",
+          `Return at most ${maxResults} sources.`,
+          "Each snippet should be short, factual, and specific to the result.",
+          "Prefer primary or official sources when they are available.",
+          "",
+          `User query: ${queryText}`
+        ].join("\n"),
+        schema: SEARCH_OUTPUT_SCHEMA,
+        tools: ["WebSearch"],
+        config,
+        context,
+        options
+      })
+    );
     return {
       provider: this.id,
-      results: parsed.sources.slice(0, maxResults).map((source) => ({
+      results: output.sources.slice(0, maxResults).map((source) => ({
         title: source.title.trim(),
         url: source.url.trim(),
         snippet: trimSnippet(source.snippet)
       }))
     };
   }
+  async answer(queryText, options, config, context) {
+    const output = parseClaudeAnswerOutput(
+      await this.runStructuredQuery({
+        prompt: [
+          "Answer the user's question using current public web information.",
+          "Use WebSearch to find relevant sources and WebFetch when you need to verify important details.",
+          "Return only a JSON object matching the provided schema.",
+          "Do not include markdown fences or extra commentary.",
+          "Keep the answer concise but informative.",
+          "Only cite sources you actually used.",
+          "",
+          `User query: ${queryText}`
+        ].join("\n"),
+        schema: ANSWER_OUTPUT_SCHEMA,
+        tools: ["WebSearch", "WebFetch"],
+        config,
+        context,
+        options
+      })
+    );
+    const lines = [];
+    lines.push(output.answer.trim() || "No answer returned.");
+    if (output.sources.length > 0) {
+      lines.push("");
+      lines.push("Sources:");
+      for (const [index, source] of output.sources.entries()) {
+        lines.push(`${index + 1}. ${source.title}`);
+        lines.push(`   ${source.url}`);
+      }
+    }
+    return {
+      provider: this.id,
+      text: lines.join("\n").trimEnd(),
+      summary: `Answer via Claude with ${output.sources.length} source(s)`,
+      itemCount: output.sources.length
+    };
+  }
+  async runStructuredQuery({
+    prompt,
+    schema,
+    tools,
+    config,
+    context,
+    options
+  }) {
+    const abortController = new AbortController();
+    if (context.signal?.aborted) {
+      abortController.abort(context.signal.reason);
+    }
+    const onAbort = () => {
+      abortController.abort(context.signal?.reason);
+    };
+    context.signal?.addEventListener("abort", onAbort, { once: true });
+    const stream = query({
+      prompt,
+      options: {
+        abortController,
+        allowedTools: tools,
+        cwd: context.cwd,
+        ...getClaudeRuntimeOptions(config, options),
+        outputFormat: {
+          type: "json_schema",
+          schema
+        },
+        pathToClaudeCodeExecutable: config.pathToClaudeCodeExecutable,
+        persistSession: false,
+        permissionMode: "dontAsk",
+        systemPrompt: {
+          type: "preset",
+          preset: "claude_code",
+          append: "Use only the provided web tools. Always produce output that matches the requested JSON schema exactly."
+        },
+        tools
+      }
+    });
+    const seenToolUseIds = /* @__PURE__ */ new Set();
+    let finalResult;
+    try {
+      for await (const message of stream) {
+        handleProgressMessage(message, seenToolUseIds, context.onProgress);
+        if (message.type === "result") {
+          finalResult = message;
+        }
+      }
+    } finally {
+      context.signal?.removeEventListener("abort", onAbort);
+      stream.close();
+    }
+    if (!finalResult) {
+      throw new Error("Claude returned no result.");
+    }
+    if (finalResult.subtype !== "success") {
+      throw new Error(
+        finalResult.errors.join("\n") || `Claude query failed (${finalResult.subtype}).`
+      );
+    }
+    return parseStructuredOutput(finalResult);
+  }
 };
-function handleProgressEvent(event, seenQueries, onProgress) {
-  if (!onProgress) return;
-  if (event.type === "item.completed" && event.item.type === "web_search" && !seenQueries.has(event.item.query)) {
-    seenQueries.add(event.item.query);
-    onProgress(`Codex web search ${seenQueries.size}: ${event.item.query}`);
+var CLAUDE_AUTH_CACHE_TTL_MS = 5e3;
+var defaultClaudeExecutablePath;
+var claudeAuthStatusCache = /* @__PURE__ */ new Map();
+function resolveClaudeExecutablePath(config) {
+  if (config.pathToClaudeCodeExecutable) {
+    return config.pathToClaudeCodeExecutable;
   }
+  if (defaultClaudeExecutablePath !== void 0) {
+    return defaultClaudeExecutablePath;
+  }
+  try {
+    const sdkEntryPath = require2.resolve("@anthropic-ai/claude-agent-sdk");
+    defaultClaudeExecutablePath = join2(dirname2(sdkEntryPath), "cli.js");
+  } catch {
+    defaultClaudeExecutablePath = void 0;
+  }
+  return defaultClaudeExecutablePath;
 }
-function parseOutput(raw) {
-  if (!raw.trim()) {
-    throw new Error("Codex returned an empty response.");
+function getClaudeAuthStatus(executablePath) {
+  if (!executablePath) {
+    return { loggedIn: false };
+  }
+  const cachedStatus = claudeAuthStatusCache.get(executablePath);
+  if (cachedStatus && Date.now() - cachedStatus.checkedAt < CLAUDE_AUTH_CACHE_TTL_MS) {
+    return { loggedIn: cachedStatus.loggedIn };
   }
+  const [command, ...args] = getClaudeAuthCommand(executablePath);
   try {
-    return JSON.parse(raw);
+    const stdout = execFileSync(command, args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    return cacheClaudeAuthStatus(executablePath, parseClaudeAuthStatus(stdout));
+  } catch (error) {
+    const stdout = getExecOutput(
+      error.stdout
+    );
+    if (stdout) {
+      return cacheClaudeAuthStatus(
+        executablePath,
+        parseClaudeAuthStatus(stdout)
+      );
+    }
+    return cacheClaudeAuthStatus(executablePath, { loggedIn: false });
+  }
+}
+function cacheClaudeAuthStatus(executablePath, status) {
+  claudeAuthStatusCache.set(executablePath, {
+    ...status,
+    checkedAt: Date.now()
+  });
+  return status;
+}
+function getClaudeAuthCommand(executablePath) {
+  const extension = extname(executablePath);
+  if (extension === ".js" || extension === ".cjs" || extension === ".mjs") {
+    return [process.execPath, executablePath, "auth", "status", "--json"];
+  }
+  return [executablePath, "auth", "status", "--json"];
+}
+function getExecOutput(output) {
+  if (typeof output === "string") {
+    return output;
+  }
+  if (Buffer.isBuffer(output)) {
+    return output.toString("utf8");
+  }
+  return "";
+}
+function parseClaudeAuthStatus(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return { loggedIn: parsed.loggedIn === true };
   } catch {
-    const match = raw.match(/\{[\s\S]*\}/);
+    return { loggedIn: false };
+  }
+}
+function handleProgressMessage(message, seenToolUseIds, onProgress) {
+  if (!onProgress || message.type !== "tool_progress") {
+    return;
+  }
+  if (seenToolUseIds.has(message.tool_use_id)) {
+    return;
+  }
+  seenToolUseIds.add(message.tool_use_id);
+  onProgress(`Claude ${formatToolName(message.tool_name)}`);
+}
+function formatToolName(toolName) {
+  if (toolName === "WebSearch") return "web search";
+  if (toolName === "WebFetch") return "web fetch";
+  return toolName;
+}
+function parseStructuredOutput(result) {
+  if (result.subtype !== "success") {
+    throw new Error("Claude query did not succeed.");
+  }
+  if (result.structured_output !== void 0) {
+    return result.structured_output;
+  }
+  if (!result.result.trim()) {
+    throw new Error("Claude returned an empty response.");
+  }
+  try {
+    return JSON.parse(result.result);
+  } catch {
+    const match = result.result.match(/\{[\s\S]*\}/);
     if (!match) {
-      throw new Error("Codex returned invalid JSON output.");
+      throw new Error("Claude returned invalid JSON output.");
     }
     return JSON.parse(match[0]);
   }
 }
-
-// src/providers/exa.ts
-import { Exa } from "exa-js";
-var ExaProvider = class {
-  id = "exa";
-  label = "Exa";
-  docsUrl = "https://exa.ai/docs/sdks/typescript-sdk-specification";
-  createTemplate() {
-    return {
-      enabled: false,
-      tools: {
-        search: true,
-        contents: true,
-        answer: true,
-        research: true
-      },
-      apiKey: "EXA_API_KEY",
-      defaults: {
+function getClaudeRuntimeOptions(config, options) {
+  const model = readNonEmptyString(options?.model) ?? config.defaults?.model;
+  const effort = readEnum(options?.effort, ["low", "medium", "high", "max"]);
+  const maxTurns = readPositiveInteger(options?.maxTurns);
+  const maxThinkingTokens = readNonNegativeInteger(options?.maxThinkingTokens);
+  const maxBudgetUsd = readPositiveNumber(options?.maxBudgetUsd);
+  const thinking = isPlainObject2(options?.thinking) ? options?.thinking : void 0;
+  return {
+    ...model ? { model } : {},
+    ...effort ?? config.defaults?.effort ? { effort: effort ?? config.defaults?.effort } : {},
+    ...maxTurns ?? config.defaults?.maxTurns ? { maxTurns: maxTurns ?? config.defaults?.maxTurns } : {},
+    ...maxThinkingTokens !== void 0 ? { maxThinkingTokens } : {},
+    ...maxBudgetUsd !== void 0 ? { maxBudgetUsd } : {},
+    ...thinking ? { thinking } : {}
+  };
+}
+function readNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+function readNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
+}
+function readPositiveNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function readEnum(value, values) {
+  return typeof value === "string" && values.includes(value) ? value : void 0;
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseClaudeSearchOutput(value) {
+  const sources = readArray(value, "sources").map((entry) => ({
+    title: readString(entry, "title"),
+    url: readString(entry, "url"),
+    snippet: readString(entry, "snippet")
+  }));
+  return { sources };
+}
+function parseClaudeAnswerOutput(value) {
+  return {
+    answer: readString(value, "answer"),
+    sources: readArray(value, "sources").map((entry) => ({
+      title: readString(entry, "title"),
+      url: readString(entry, "url")
+    }))
+  };
+}
+function readArray(value, key) {
+  if (typeof value !== "object" || value === null || !(key in value)) {
+    throw new Error(`Claude output is missing '${key}'.`);
+  }
+  const entry = value[key];
+  if (!Array.isArray(entry)) {
+    throw new Error(`Claude output field '${key}' must be an array.`);
+  }
+  return entry;
+}
+function readString(value, key) {
+  if (typeof value !== "object" || value === null || !(key in value)) {
+    throw new Error(`Claude output is missing '${key}'.`);
+  }
+  const entry = value[key];
+  if (typeof entry !== "string") {
+    throw new Error(`Claude output field '${key}' must be a string.`);
+  }
+  return entry;
+}
+
+// src/providers/codex.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { join as join3 } from "node:path";
+import { Codex } from "@openai/codex-sdk";
+var OUTPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    sources: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          title: { type: "string" },
+          url: { type: "string" },
+          snippet: { type: "string" }
+        },
+        required: ["title", "url", "snippet"]
+      }
+    }
+  },
+  required: ["sources"]
+};
+var CodexProvider = class {
+  id = "codex";
+  label = "Codex";
+  docsUrl = "https://github.com/openai/codex/tree/main/sdk/typescript";
+  createTemplate() {
+    return {
+      enabled: true,
+      tools: {
+        search: true
+      },
+      defaults: {
+        networkAccessEnabled: true,
+        webSearchEnabled: true,
+        webSearchMode: "live"
+      }
+    };
+  }
+  getStatus(config, _cwd) {
+    if (!config) {
+      return { available: false, summary: "not configured" };
+    }
+    if (config.enabled === false) {
+      return { available: false, summary: "disabled" };
+    }
+    try {
+      new Codex({
+        codexPathOverride: config.codexPath,
+        config: config.config
+      });
+    } catch (error) {
+      return {
+        available: false,
+        summary: error.message
+      };
+    }
+    if (!hasCodexCredentials(config)) {
+      return { available: false, summary: "missing Codex auth" };
+    }
+    return { available: true, summary: "enabled" };
+  }
+  async search(query2, maxResults, options, config, context) {
+    const codex = new Codex({
+      codexPathOverride: config.codexPath,
+      baseUrl: config.baseUrl,
+      apiKey: resolveConfigValue(config.apiKey),
+      config: config.config,
+      env: resolveEnvMap(config.env)
+    });
+    const thread = codex.startThread(
+      buildCodexSearchThreadOptions(config, context.cwd, options)
+    );
+    const prompt = [
+      "You are performing web research for another coding agent.",
+      "Search the public web and return only a JSON object matching the provided schema.",
+      "Do not include markdown fences or extra commentary.",
+      `Return at most ${maxResults} sources.`,
+      "Prefer primary or official sources when they are available.",
+      "Each snippet should be short and specific.",
+      "",
+      `User query: ${query2}`
+    ].join("\n");
+    const streamed = await thread.runStreamed(prompt, {
+      outputSchema: OUTPUT_SCHEMA,
+      signal: context.signal
+    });
+    let finalResponse = "";
+    const seenQueries = /* @__PURE__ */ new Set();
+    for await (const event of streamed.events) {
+      handleProgressEvent(event, seenQueries, context.onProgress);
+      if (event.type === "item.completed" && event.item.type === "agent_message") {
+        finalResponse = event.item.text;
+      }
+      if (event.type === "turn.failed") {
+        throw new Error(event.error.message);
+      }
+    }
+    const parsed = parseOutput(finalResponse);
+    return {
+      provider: this.id,
+      results: parsed.sources.slice(0, maxResults).map((source) => ({
+        title: source.title.trim(),
+        url: source.url.trim(),
+        snippet: trimSnippet(source.snippet)
+      }))
+    };
+  }
+};
+function buildCodexSearchThreadOptions(config, cwd, options) {
+  const runtimeOptions = getCodexSearchRuntimeOptions(options);
+  return {
+    additionalDirectories: config.defaults?.additionalDirectories,
+    approvalPolicy: "never",
+    model: runtimeOptions.model ?? config.defaults?.model,
+    modelReasoningEffort: runtimeOptions.modelReasoningEffort ?? config.defaults?.modelReasoningEffort,
+    networkAccessEnabled: config.defaults?.networkAccessEnabled ?? true,
+    sandboxMode: "read-only",
+    skipGitRepoCheck: true,
+    webSearchEnabled: config.defaults?.webSearchEnabled ?? true,
+    webSearchMode: runtimeOptions.webSearchMode ?? config.defaults?.webSearchMode ?? "live",
+    workingDirectory: cwd
+  };
+}
+function getCodexSearchRuntimeOptions(options) {
+  if (!options) {
+    return {};
+  }
+  const model = readNonEmptyString2(options.model);
+  const modelReasoningEffort = readEnum2(options.modelReasoningEffort, [
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh"
+  ]);
+  const webSearchMode = readEnum2(options.webSearchMode, [
+    "disabled",
+    "cached",
+    "live"
+  ]);
+  return {
+    ...model ? { model } : {},
+    ...modelReasoningEffort ? { modelReasoningEffort } : {},
+    ...webSearchMode ? { webSearchMode } : {}
+  };
+}
+function readNonEmptyString2(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function readEnum2(value, values) {
+  return typeof value === "string" && values.includes(value) ? value : void 0;
+}
+function hasCodexCredentials(config) {
+  if (hasConfiguredReference(config.apiKey)) {
+    return true;
+  }
+  if (hasConfiguredReference(config.env?.CODEX_API_KEY) || hasConfiguredReference(config.env?.OPENAI_API_KEY)) {
+    return true;
+  }
+  if (!config.env) {
+    const inheritedKey = process.env.CODEX_API_KEY ?? process.env.OPENAI_API_KEY;
+    if (typeof inheritedKey === "string" && inheritedKey.trim().length > 0) {
+      return true;
+    }
+  }
+  return existsSync2(join3(homedir(), ".codex", "auth.json"));
+}
+function hasConfiguredReference(reference) {
+  if (!reference) {
+    return false;
+  }
+  if (reference.startsWith("!")) {
+    return reference.slice(1).trim().length > 0;
+  }
+  const envValue = process.env[reference];
+  if (typeof envValue === "string") {
+    return envValue.trim().length > 0;
+  }
+  if (/^[A-Z][A-Z0-9_]*$/.test(reference)) {
+    return false;
+  }
+  return reference.trim().length > 0;
+}
+function handleProgressEvent(event, seenQueries, onProgress) {
+  if (!onProgress) return;
+  if (event.type === "item.completed" && event.item.type === "web_search" && !seenQueries.has(event.item.query)) {
+    seenQueries.add(event.item.query);
+    onProgress(`Codex web search ${seenQueries.size}: ${event.item.query}`);
+  }
+}
+function parseOutput(raw) {
+  if (!raw.trim()) {
+    throw new Error("Codex returned an empty response.");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    const match = raw.match(/\{[\s\S]*\}/);
+    if (!match) {
+      throw new Error("Codex returned invalid JSON output.");
+    }
+    return JSON.parse(match[0]);
+  }
+}
+
+// src/providers/exa.ts
+import { Exa } from "exa-js";
+var ExaProvider = class {
+  id = "exa";
+  label = "Exa";
+  docsUrl = "https://exa.ai/docs/sdks/typescript-sdk-specification";
+  createTemplate() {
+    return {
+      enabled: false,
+      tools: {
+        search: true,
+        contents: true,
+        answer: true,
+        research: true
+      },
+      apiKey: "EXA_API_KEY",
+      defaults: {
         type: "auto",
         contents: {
           text: true
@@ -713,7 +1317,7 @@ var ExaProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query, maxResults, config, context) {
+  async search(query2, maxResults, searchOptions, config, context) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
       throw new Error("Exa is missing an API key.");
@@ -721,10 +1325,11 @@ var ExaProvider = class {
     const client = new Exa(apiKey, config.baseUrl);
     const options = {
       ...asJsonObject(config.defaults),
+      ...searchOptions ?? {},
       numResults: maxResults
     };
-    context.onProgress?.(`Searching Exa for: ${query}`);
-    const response = await client.search(query, options);
+    context.onProgress?.(`Searching Exa for: ${query2}`);
+    const response = await client.search(query2, options);
     return {
       provider: this.id,
       results: (response.results ?? []).slice(0, maxResults).map((result) => ({
@@ -743,11 +1348,15 @@ var ExaProvider = class {
       throw new Error("Exa is missing an API key.");
     }
     const client = new Exa(apiKey, config.baseUrl);
-    context.onProgress?.(`Fetching contents from Exa for ${urls.length} URL(s)`);
+    context.onProgress?.(
+      `Fetching contents from Exa for ${urls.length} URL(s)`
+    );
     const response = await client.getContents(urls, options);
     const lines = [];
     for (const [index, result] of (response.results ?? []).entries()) {
-      lines.push(`${index + 1}. ${String(result.title ?? result.url ?? "Untitled")}`);
+      lines.push(
+        `${index + 1}. ${String(result.title ?? result.url ?? "Untitled")}`
+      );
       lines.push(`   ${String(result.url ?? "")}`);
       const summary = typeof result.summary === "string" ? result.summary : result.summary ? formatJson(result.summary) : void 0;
       const text = typeof result.text === "string" ? result.text : Array.isArray(result.highlights) ? result.highlights.join(" ") : "";
@@ -764,14 +1373,14 @@ var ExaProvider = class {
       itemCount: response.results?.length ?? 0
     };
   }
-  async answer(query, options, config, context) {
+  async answer(query2, options, config, context) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
       throw new Error("Exa is missing an API key.");
     }
     const client = new Exa(apiKey, config.baseUrl);
-    context.onProgress?.(`Getting Exa answer for: ${query}`);
-    const response = await client.answer(query, options);
+    context.onProgress?.(`Getting Exa answer for: ${query2}`);
+    const response = await client.answer(query2, options);
     const lines = [];
     lines.push(
       typeof response.answer === "string" ? response.answer : formatJson(response.answer)
@@ -781,7 +1390,9 @@ var ExaProvider = class {
       lines.push("");
       lines.push("Sources:");
       for (const [index, citation] of citations.entries()) {
-        lines.push(`${index + 1}. ${String(citation.title ?? citation.url ?? "Untitled")}`);
+        lines.push(
+          `${index + 1}. ${String(citation.title ?? citation.url ?? "Untitled")}`
+        );
         lines.push(`   ${String(citation.url ?? "")}`);
       }
     }
@@ -823,6 +1434,7 @@ var ExaProvider = class {
 // src/providers/gemini.ts
 import { GoogleGenAI } from "@google/genai";
 var DEFAULT_SEARCH_MODEL = "gemini-2.5-flash";
+var DEFAULT_CONTENTS_MODEL = "gemini-2.5-flash";
 var DEFAULT_ANSWER_MODEL = "gemini-2.5-flash";
 var DEFAULT_RESEARCH_AGENT = "deep-research-pro-preview-12-2025";
 var DEFAULT_POLL_INTERVAL_MS = 3e3;
@@ -835,12 +1447,14 @@ var GeminiProvider = class {
       enabled: false,
       tools: {
         search: true,
+        contents: true,
         answer: true,
         research: true
       },
       apiKey: "GOOGLE_API_KEY",
       defaults: {
         searchModel: DEFAULT_SEARCH_MODEL,
+        contentsModel: DEFAULT_CONTENTS_MODEL,
         answerModel: DEFAULT_ANSWER_MODEL,
         researchAgent: DEFAULT_RESEARCH_AGENT
       }
@@ -859,39 +1473,90 @@ var GeminiProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query, maxResults, config, context) {
+  async search(query2, maxResults, options, config, context) {
     const ai = this.createClient(config);
-    const model = config.defaults?.searchModel ?? DEFAULT_SEARCH_MODEL;
-    context.onProgress?.(`Searching Gemini for: ${query}`);
-    const interaction = await ai.interactions.create({
-      model,
-      input: query,
-      tools: [{ type: "google_search" }],
-      generation_config: {
-        tool_choice: "any"
-      }
-    });
-    const results = extractGoogleSearchResults(interaction.outputs).slice(0, maxResults).map((result) => ({
-      title: result.title ?? result.url ?? "Untitled",
-      url: result.url ?? "",
-      snippet: trimSnippet(result.rendered_content ?? "")
-    }));
+    const request = buildGeminiSearchRequest(
+      query2,
+      config.defaults?.searchModel ?? DEFAULT_SEARCH_MODEL,
+      options
+    );
+    context.onProgress?.(`Searching Gemini for: ${query2}`);
+    const interaction = await createSearchInteraction(ai, request);
+    const results = await Promise.all(
+      extractGoogleSearchResults(interaction.outputs).slice(0, maxResults).map(async (result) => {
+        const resolvedUrl = await resolveGoogleSearchUrl(result.url);
+        return {
+          title: result.title ?? resolvedUrl ?? result.url ?? "Untitled",
+          url: resolvedUrl ?? result.url ?? "",
+          snippet: ""
+        };
+      })
+    );
     return {
       provider: this.id,
       results
     };
   }
-  async answer(query, options, config, context) {
+  async contents(urls, options, config, context) {
     const ai = this.createClient(config);
-    const model = config.defaults?.answerModel ?? DEFAULT_ANSWER_MODEL;
-    context.onProgress?.(`Getting Gemini answer for: ${query}`);
+    context.onProgress?.(
+      `Fetching contents from Gemini for ${urls.length} URL(s)`
+    );
+    const urlList = urls.map((url) => `- ${url}`).join("\n");
+    const request = buildGeminiGenerateContentRequest({
+      defaultModel: config.defaults?.contentsModel ?? DEFAULT_CONTENTS_MODEL,
+      prompt: `Extract the main textual content from each of the following URLs. For each URL, return the page title followed by the cleaned body text. Preserve the original structure (headings, paragraphs, lists) but remove navigation, ads, and boilerplate.
+
+${urlList}`,
+      options,
+      toolConfig: { urlContext: {} }
+    });
     const response = await ai.models.generateContent({
-      model,
-      contents: query,
-      config: {
-        ...options ?? {},
-        tools: [{ googleSearch: {} }]
+      model: request.model,
+      contents: [request.contents],
+      config: request.config
+    });
+    const text = response.text?.trim() || "";
+    const metadata = extractUrlContextMetadata(response.candidates);
+    const lines = [];
+    if (text) {
+      lines.push(text);
+    }
+    if (metadata.length > 0) {
+      const failures = metadata.filter(
+        (entry) => entry.status !== "URL_RETRIEVAL_STATUS_SUCCESS" && entry.status !== void 0
+      );
+      if (failures.length > 0) {
+        lines.push("");
+        lines.push("Retrieval issues:");
+        for (const failure of failures) {
+          lines.push(`- ${failure.url}: ${failure.status}`);
+        }
       }
+    }
+    const successCount = metadata.filter(
+      (entry) => entry.status === "URL_RETRIEVAL_STATUS_SUCCESS" || entry.status === void 0
+    ).length;
+    return {
+      provider: this.id,
+      text: lines.join("\n").trimEnd() || "No contents extracted.",
+      summary: `${successCount} of ${urls.length} URL(s) extracted via Gemini`,
+      itemCount: successCount
+    };
+  }
+  async answer(query2, options, config, context) {
+    const ai = this.createClient(config);
+    const request = buildGeminiGenerateContentRequest({
+      defaultModel: config.defaults?.answerModel ?? DEFAULT_ANSWER_MODEL,
+      prompt: query2,
+      options,
+      toolConfig: { googleSearch: {} }
+    });
+    context.onProgress?.(`Getting Gemini answer for: ${query2}`);
+    const response = await ai.models.generateContent({
+      model: request.model,
+      contents: request.contents,
+      config: request.config
     });
     const lines = [];
     lines.push(response.text?.trim() || "No answer returned.");
@@ -903,7 +1568,9 @@ var GeminiProvider = class {
       lines.push("Sources:");
       for (const [index, source] of sources.entries()) {
         lines.push(`${index + 1}. ${source.title}`);
-        lines.push(`   ${source.url}`);
+        if (source.url) {
+          lines.push(`   ${source.url}`);
+        }
       }
     }
     return {
@@ -917,7 +1584,11 @@ var GeminiProvider = class {
     const ai = this.createClient(config);
     const agent = config.defaults?.researchAgent ?? DEFAULT_RESEARCH_AGENT;
     const pollIntervalMs = getPollInterval(options);
-    const requestOptions = stripPollIntervalOption(options);
+    const requestOptions = getGeminiResearchRequestOptions(
+      stripPollIntervalOption(options)
+    );
+    const startedAt = Date.now();
+    let lastStatus;
     context.onProgress?.("Starting Gemini deep research");
     const initialInteraction = await ai.interactions.create({
       ...requestOptions,
@@ -931,7 +1602,13 @@ var GeminiProvider = class {
         throw new Error("Gemini research aborted.");
       }
       const interaction = await ai.interactions.get(initialInteraction.id);
-      context.onProgress?.(`Gemini research status: ${interaction.status}`);
+      const now = Date.now();
+      if (interaction.status !== lastStatus) {
+        context.onProgress?.(
+          `Gemini research status: ${interaction.status} (${formatElapsed(now - startedAt)} elapsed)`
+        );
+        lastStatus = interaction.status;
+      }
       if (interaction.status === "completed") {
         const text = formatInteractionOutputs(interaction.outputs);
         return {
@@ -943,112 +1620,482 @@ var GeminiProvider = class {
       if (interaction.status === "failed" || interaction.status === "cancelled") {
         throw new Error(`Gemini research ${interaction.status}.`);
       }
-      await sleep(pollIntervalMs, context.signal);
+      await sleep(pollIntervalMs, context.signal);
+    }
+  }
+  createClient(config) {
+    const apiKey = resolveConfigValue(config.apiKey);
+    if (!apiKey) {
+      throw new Error("Gemini is missing an API key.");
+    }
+    return new GoogleGenAI({
+      apiKey,
+      apiVersion: config.defaults?.apiVersion
+    });
+  }
+};
+function extractGoogleSearchResults(outputs) {
+  const results = [];
+  if (!Array.isArray(outputs)) {
+    return results;
+  }
+  for (const output of outputs) {
+    if (typeof output !== "object" || output === null) {
+      continue;
+    }
+    const content = output;
+    if (content.type !== "google_search_result") {
+      continue;
+    }
+    const items = Array.isArray(content.result) ? content.result : [];
+    for (const item of items) {
+      if (typeof item !== "object" || item === null) {
+        continue;
+      }
+      const record = item;
+      results.push({
+        title: typeof record.title === "string" ? record.title : void 0,
+        url: typeof record.url === "string" ? record.url : void 0,
+        rendered_content: typeof record.rendered_content === "string" ? record.rendered_content : void 0
+      });
+    }
+  }
+  return results;
+}
+function extractGroundingSources(chunks) {
+  const seen = /* @__PURE__ */ new Set();
+  const sources = [];
+  const maxSources = 5;
+  if (!Array.isArray(chunks)) {
+    return sources;
+  }
+  for (const chunk of chunks) {
+    const web = typeof chunk === "object" && chunk !== null && "web" in chunk && typeof chunk.web === "object" && chunk.web !== null ? chunk.web : void 0;
+    if (!web) continue;
+    const rawUrl = typeof web.uri === "string" ? web.uri : "";
+    const title = formatGroundingSourceTitle(
+      typeof web.title === "string" ? web.title : rawUrl,
+      rawUrl
+    );
+    const url = formatGroundingSourceUrl(rawUrl);
+    const key = [title.toLowerCase(), url.toLowerCase()].join("::");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    sources.push({
+      title,
+      url
+    });
+    if (sources.length >= maxSources) {
+      break;
+    }
+  }
+  return sources;
+}
+function extractUrlContextMetadata(candidates) {
+  const results = [];
+  if (!Array.isArray(candidates)) {
+    return results;
+  }
+  for (const candidate of candidates) {
+    if (typeof candidate !== "object" || candidate === null) {
+      continue;
+    }
+    const metadata = candidate.urlContextMetadata;
+    if (!metadata?.urlMetadata || !Array.isArray(metadata.urlMetadata)) {
+      continue;
+    }
+    for (const entry of metadata.urlMetadata) {
+      if (typeof entry !== "object" || entry === null) {
+        continue;
+      }
+      results.push({
+        url: typeof entry.retrievedUrl === "string" ? entry.retrievedUrl : "unknown",
+        status: typeof entry.urlRetrievalStatus === "string" ? entry.urlRetrievalStatus : void 0
+      });
+    }
+  }
+  return results;
+}
+function formatInteractionOutputs(outputs) {
+  const lines = [];
+  if (!Array.isArray(outputs)) {
+    return "";
+  }
+  for (const output of outputs) {
+    if (typeof output === "object" && output !== null && "type" in output && output.type === "text" && "text" in output && typeof output.text === "string") {
+      const text = output.text.trim();
+      if (text) {
+        lines.push(text);
+      }
+    }
+  }
+  return lines.join("\n\n").trim();
+}
+function formatGroundingSourceTitle(title, url) {
+  const trimmedTitle = title?.trim();
+  if (trimmedTitle) {
+    return trimmedTitle;
+  }
+  if (url) {
+    try {
+      return new URL(url).hostname;
+    } catch {
+      return url;
+    }
+  }
+  return "Untitled";
+}
+function formatGroundingSourceUrl(url) {
+  if (!url) {
+    return "";
+  }
+  if (isGoogleGroundingRedirect(url)) {
+    return "";
+  }
+  return url;
+}
+function isGoogleGroundingRedirect(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.hostname === "vertexaisearch.cloud.google.com" && parsed.pathname.startsWith("/grounding-api-redirect/");
+  } catch {
+    return false;
+  }
+}
+async function createSearchInteraction(ai, request) {
+  const forcedRequest = {
+    ...request,
+    ...request.generation_config ? {
+      generation_config: {
+        ...request.generation_config,
+        tool_choice: "any"
+      }
+    } : {
+      generation_config: {
+        tool_choice: "any"
+      }
+    }
+  };
+  try {
+    return await ai.interactions.create(forcedRequest);
+  } catch (error) {
+    if (!isBuiltInToolChoiceError(error)) {
+      throw error;
+    }
+    const fallbackGenerationConfig = stripToolChoice(request.generation_config);
+    return ai.interactions.create({
+      ...request,
+      ...fallbackGenerationConfig ? { generation_config: fallbackGenerationConfig } : {}
+    });
+  }
+}
+function isBuiltInToolChoiceError(error) {
+  if (error instanceof Error) {
+    return error.message.includes(
+      "Function calling config is set without function_declarations"
+    );
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message.includes(
+      "Function calling config is set without function_declarations"
+    );
+  }
+  return false;
+}
+async function resolveGoogleSearchUrl(url) {
+  if (!url) {
+    return void 0;
+  }
+  if (!isGoogleGroundingRedirect(url)) {
+    return url;
+  }
+  try {
+    const response = await fetch(url, {
+      method: "HEAD",
+      redirect: "manual"
+    });
+    return response.headers.get("location") || url;
+  } catch {
+    return url;
+  }
+}
+async function sleep(ms, signal) {
+  if (signal?.aborted) {
+    throw new Error("Operation aborted.");
+  }
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(new Error("Operation aborted."));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function formatElapsed(ms) {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1e3));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${totalSeconds}s`;
+}
+function getPollInterval(options) {
+  const raw = options?.pollIntervalMs;
+  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 1e3) {
+    return Math.trunc(raw);
+  }
+  return DEFAULT_POLL_INTERVAL_MS;
+}
+function stripPollIntervalOption(options) {
+  if (!options || !Object.hasOwn(options, "pollIntervalMs")) {
+    return options;
+  }
+  const { pollIntervalMs: _ignored, ...rest } = options;
+  return rest;
+}
+function buildGeminiSearchRequest(query2, defaultModel, options) {
+  return {
+    model: readNonEmptyString3(options?.model) ?? defaultModel,
+    input: query2,
+    tools: [{ type: "google_search" }],
+    ...isPlainObject3(options?.generation_config) ? { generation_config: options.generation_config } : {}
+  };
+}
+function buildGeminiGenerateContentRequest({
+  defaultModel,
+  prompt,
+  options,
+  toolConfig
+}) {
+  const requestOptions = isPlainObject3(options) ? options : {};
+  const explicitConfig = isPlainObject3(requestOptions.config) ? requestOptions.config : {};
+  return {
+    model: readNonEmptyString3(requestOptions.model) ?? defaultModel,
+    contents: prompt,
+    config: {
+      ...explicitConfig,
+      tools: [toolConfig]
+    }
+  };
+}
+function getGeminiResearchRequestOptions(options) {
+  if (!isPlainObject3(options)) {
+    return {};
+  }
+  return { ...options };
+}
+function stripToolChoice(generationConfig) {
+  if (!generationConfig || !Object.hasOwn(generationConfig, "tool_choice")) {
+    return generationConfig;
+  }
+  const { tool_choice: _ignored, ...rest } = generationConfig;
+  return Object.keys(rest).length > 0 ? rest : void 0;
+}
+function isPlainObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readNonEmptyString3(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+
+// src/providers/perplexity.ts
+import Perplexity from "@perplexity-ai/perplexity_ai";
+var DEFAULT_ANSWER_MODEL2 = "sonar";
+var DEFAULT_RESEARCH_MODEL = "sonar-deep-research";
+var PerplexityProvider = class {
+  id = "perplexity";
+  label = "Perplexity";
+  docsUrl = "https://docs.perplexity.ai/docs/sdk/overview.md";
+  createTemplate() {
+    return {
+      enabled: false,
+      tools: {
+        search: true,
+        answer: true,
+        research: true
+      },
+      apiKey: "PERPLEXITY_API_KEY",
+      defaults: {
+        answer: {
+          model: DEFAULT_ANSWER_MODEL2
+        },
+        research: {
+          model: DEFAULT_RESEARCH_MODEL
+        }
+      }
+    };
+  }
+  getStatus(config) {
+    if (!config) {
+      return { available: false, summary: "not configured" };
+    }
+    if (config.enabled === false) {
+      return { available: false, summary: "disabled" };
+    }
+    const apiKey = resolveConfigValue(config.apiKey);
+    if (!apiKey) {
+      return { available: false, summary: "missing apiKey" };
+    }
+    return { available: true, summary: "enabled" };
+  }
+  async search(query2, maxResults, options, config, context) {
+    const client = this.createClient(config);
+    const request = {
+      ...asJsonObject(config.defaults?.search),
+      ...options ?? {},
+      query: query2,
+      max_results: maxResults
+    };
+    context.onProgress?.(`Searching Perplexity for: ${query2}`);
+    const response = await client.search.create(
+      request,
+      buildRequestOptions(context)
+    );
+    return {
+      provider: this.id,
+      results: response.results.slice(0, maxResults).map((result) => ({
+        title: result.title,
+        url: result.url,
+        snippet: trimSnippet(result.snippet),
+        metadata: result.date || result.last_updated ? {
+          ...result.date ? { date: result.date } : {},
+          ...result.last_updated ? { last_updated: result.last_updated } : {}
+        } : void 0
+      }))
+    };
+  }
+  async answer(query2, options, config, context) {
+    context.onProgress?.(`Getting Perplexity answer for: ${query2}`);
+    return this.runChatTool(
+      query2,
+      options,
+      config,
+      context,
+      DEFAULT_ANSWER_MODEL2,
+      "Answer"
+    );
+  }
+  async research(input, options, config, context) {
+    context.onProgress?.("Starting Perplexity research");
+    return this.runChatTool(
+      input,
+      options,
+      config,
+      context,
+      DEFAULT_RESEARCH_MODEL,
+      "Research",
+      true
+    );
+  }
+  async runChatTool(input, options, config, context, fallbackModel, label, isResearch = false) {
+    const client = this.createClient(config);
+    const defaults = isResearch ? config.defaults?.research : config.defaults?.answer;
+    const request = {
+      ...asJsonObject(defaults),
+      ...options ?? {},
+      messages: [{ role: "user", content: input }],
+      model: resolveModel(
+        (options ?? {}).model,
+        asJsonObject(defaults).model,
+        fallbackModel
+      ) ?? fallbackModel,
+      stream: false
+    };
+    const response = await client.chat.completions.create(
+      request,
+      buildRequestOptions(context)
+    );
+    const content = extractMessageText(response.choices[0]?.message?.content);
+    const sources = dedupeSources(extractSources(response));
+    const lines = [];
+    lines.push(content || `No ${label.toLowerCase()} returned.`);
+    if (sources.length > 0) {
+      lines.push("");
+      lines.push("Sources:");
+      for (const [index, source] of sources.entries()) {
+        lines.push(`${index + 1}. ${source.title}`);
+        lines.push(`   ${source.url}`);
+      }
     }
+    return {
+      provider: this.id,
+      text: lines.join("\n").trimEnd(),
+      summary: `${label} via Perplexity with ${sources.length} source(s)`,
+      itemCount: sources.length
+    };
   }
   createClient(config) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
-      throw new Error("Gemini is missing an API key.");
+      throw new Error("Perplexity is missing an API key.");
     }
-    return new GoogleGenAI({
+    return new Perplexity({
       apiKey,
-      apiVersion: config.defaults?.apiVersion
+      baseURL: resolveConfigValue(config.baseUrl)
     });
   }
 };
-function extractGoogleSearchResults(outputs) {
-  const results = [];
-  if (!Array.isArray(outputs)) {
-    return results;
+function resolveModel(optionModel, defaultModel, fallbackModel) {
+  if (typeof optionModel === "string" && optionModel.trim().length > 0) {
+    return optionModel;
   }
-  for (const output of outputs) {
-    if (typeof output !== "object" || output === null) {
-      continue;
-    }
-    const content = output;
-    if (content.type !== "google_search_result") {
-      continue;
-    }
-    const items = Array.isArray(content.result) ? content.result : [];
-    for (const item of items) {
-      if (typeof item !== "object" || item === null) {
-        continue;
-      }
-      const record = item;
-      results.push({
-        title: typeof record.title === "string" ? record.title : void 0,
-        url: typeof record.url === "string" ? record.url : void 0,
-        rendered_content: typeof record.rendered_content === "string" ? record.rendered_content : void 0
-      });
-    }
+  if (typeof defaultModel === "string" && defaultModel.trim().length > 0) {
+    return defaultModel;
   }
-  return results;
+  return fallbackModel;
 }
-function extractGroundingSources(chunks) {
-  const seen = /* @__PURE__ */ new Set();
-  const sources = [];
-  if (!Array.isArray(chunks)) {
-    return sources;
-  }
-  for (const chunk of chunks) {
-    const web = typeof chunk === "object" && chunk !== null && "web" in chunk && typeof chunk.web === "object" && chunk.web !== null ? chunk.web : void 0;
-    if (!web) continue;
-    const url = typeof web.uri === "string" ? web.uri : void 0;
-    if (!url || seen.has(url)) continue;
-    seen.add(url);
-    sources.push({
-      title: typeof web.title === "string" ? web.title : url,
-      url
-    });
+function extractMessageText(content) {
+  if (typeof content === "string") {
+    return content.trim();
   }
-  return sources;
-}
-function formatInteractionOutputs(outputs) {
-  const lines = [];
-  if (!Array.isArray(outputs)) {
+  if (!Array.isArray(content)) {
     return "";
   }
-  for (const output of outputs) {
-    if (typeof output === "object" && output !== null && "type" in output && output.type === "text" && "text" in output && typeof output.text === "string") {
-      const text = output.text.trim();
-      if (text) {
-        lines.push(text);
-      }
+  return content.flatMap((chunk) => {
+    if (typeof chunk === "object" && chunk !== null && "type" in chunk && chunk.type === "text" && "text" in chunk && typeof chunk.text === "string") {
+      return [chunk.text.trim()];
     }
-  }
-  return lines.join("\n\n").trim();
+    return [];
+  }).filter((text) => text.length > 0).join("\n\n").trim();
 }
-async function sleep(ms, signal) {
-  if (signal?.aborted) {
-    throw new Error("Operation aborted.");
+function dedupeSources(sources) {
+  const seen = /* @__PURE__ */ new Set();
+  const unique = [];
+  for (const source of sources) {
+    const title = source.title.trim() || source.url.trim() || "Untitled";
+    const url = source.url.trim();
+    if (!url) continue;
+    const key = `${title.toLowerCase()}::${url.toLowerCase()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push({ title, url });
   }
-  await new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      reject(new Error("Operation aborted."));
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
+  return unique;
 }
-function getPollInterval(options) {
-  const raw = options?.pollIntervalMs;
-  if (typeof raw === "number" && Number.isFinite(raw) && raw >= 1e3) {
-    return Math.trunc(raw);
+function extractSources(response) {
+  const searchResults = response.search_results?.flatMap((result) => {
+    const url = result.url?.trim() ?? "";
+    if (!url) {
+      return [];
+    }
+    return [{ title: result.title?.trim() ?? url, url }];
+  }) ?? [];
+  if (searchResults.length > 0) {
+    return searchResults;
   }
-  return DEFAULT_POLL_INTERVAL_MS;
+  return response.citations?.flatMap((citation) => {
+    const url = citation?.trim() ?? "";
+    return url ? [{ title: url, url }] : [];
+  }) ?? [];
 }
-function stripPollIntervalOption(options) {
-  if (!options || !Object.hasOwn(options, "pollIntervalMs")) {
-    return options;
-  }
-  const { pollIntervalMs: _ignored, ...rest } = options;
-  return rest;
+function buildRequestOptions(context) {
+  return context.signal ? { signal: context.signal } : void 0;
 }
 
 // src/providers/parallel.ts
@@ -1089,13 +2136,14 @@ var ParallelProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query, maxResults, config, context) {
+  async search(query2, maxResults, options, config, context) {
     const client = this.createClient(config);
     const defaults = asJsonObject(config.defaults?.search);
-    context.onProgress?.(`Searching Parallel for: ${query}`);
+    context.onProgress?.(`Searching Parallel for: ${query2}`);
     const response = await client.beta.search({
       ...defaults,
-      objective: query,
+      ...options ?? {},
+      objective: query2,
       max_results: maxResults
     });
     return {
@@ -1192,7 +2240,7 @@ var ValyuProvider = class {
     }
     return { available: true, summary: "enabled" };
   }
-  async search(query, maxResults, config, context) {
+  async search(query2, maxResults, searchOptions, config, context) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
       throw new Error("Valyu is missing an API key.");
@@ -1200,10 +2248,11 @@ var ValyuProvider = class {
     const client = new Valyu(apiKey, config.baseUrl);
     const options = {
       ...asJsonObject(config.defaults),
+      ...searchOptions ?? {},
       maxNumResults: maxResults
     };
-    context.onProgress?.(`Searching Valyu for: ${query}`);
-    const response = await client.search(query, options);
+    context.onProgress?.(`Searching Valyu for: ${query2}`);
+    const response = await client.search(query2, options);
     if (!response.success) {
       throw new Error(response.error || "Valyu search failed.");
     }
@@ -1225,7 +2274,9 @@ var ValyuProvider = class {
       throw new Error("Valyu is missing an API key.");
     }
     const client = new Valyu(apiKey, config.baseUrl);
-    context.onProgress?.(`Fetching contents from Valyu for ${urls.length} URL(s)`);
+    context.onProgress?.(
+      `Fetching contents from Valyu for ${urls.length} URL(s)`
+    );
     const response = await client.contents(urls, options);
     const finalResponse = "jobId" in response ? await client.waitForJob(response.jobId, {
       onProgress: (status) => context.onProgress?.(
@@ -1257,14 +2308,14 @@ var ValyuProvider = class {
       itemCount: results.length
     };
   }
-  async answer(query, options, config, context) {
+  async answer(query2, options, config, context) {
     const apiKey = resolveConfigValue(config.apiKey);
     if (!apiKey) {
       throw new Error("Valyu is missing an API key.");
     }
     const client = new Valyu(apiKey, config.baseUrl);
-    context.onProgress?.(`Getting Valyu answer for: ${query}`);
-    const response = await client.answer(query, {
+    context.onProgress?.(`Getting Valyu answer for: ${query2}`);
+    const response = await client.answer(query2, {
       ...options ?? {},
       streaming: false
     });
@@ -1343,45 +2394,57 @@ var ValyuProvider = class {
 
 // src/providers/index.ts
 var PROVIDERS = [
+  new ClaudeProvider(),
   new CodexProvider(),
   new ExaProvider(),
   new GeminiProvider(),
+  new PerplexityProvider(),
   new ParallelProvider(),
   new ValyuProvider()
 ];
 var PROVIDER_MAP = {
-  codex: PROVIDERS[0],
-  exa: PROVIDERS[1],
-  gemini: PROVIDERS[2],
-  parallel: PROVIDERS[3],
-  valyu: PROVIDERS[4]
+  claude: PROVIDERS[0],
+  codex: PROVIDERS[1],
+  exa: PROVIDERS[2],
+  gemini: PROVIDERS[3],
+  perplexity: PROVIDERS[4],
+  parallel: PROVIDERS[5],
+  valyu: PROVIDERS[6]
 };
 
 // src/provider-resolution.ts
+var IMPLICIT_PROVIDER_FALLBACKS = ["codex"];
 function resolveProviderChoice(config, explicit, cwd) {
   return resolveProviderForCapability(config, explicit, cwd, "search");
 }
+function getEffectiveProviderConfig(config, providerId) {
+  const configured = config.providers?.[providerId];
+  if (configured) {
+    return configured;
+  }
+  if (IMPLICIT_PROVIDER_FALLBACKS.includes(providerId)) {
+    return {
+      ...PROVIDER_MAP[providerId].createTemplate(),
+      enabled: true
+    };
+  }
+  return void 0;
+}
 function resolveProviderForCapability(config, explicit, cwd, capability) {
   if (explicit) {
     const provider = PROVIDER_MAP[explicit];
+    const providerConfig = getEffectiveProviderConfig(config, explicit);
     if (typeof provider[capability] !== "function") {
       throw new Error(
         `Provider '${explicit}' does not support '${capability}'.`
       );
     }
-    if (!isProviderToolEnabled(
-      explicit,
-      config.providers?.[explicit],
-      capability
-    )) {
+    if (!isProviderToolEnabled(explicit, providerConfig, capability)) {
       throw new Error(
         `Provider '${explicit}' has '${capability}' disabled in config.`
       );
     }
-    const status = provider.getStatus(
-      config.providers?.[explicit],
-      cwd
-    );
+    const status = provider.getStatus(providerConfig, cwd);
     if (!status.available) {
       throw new Error(
         `Provider '${explicit}' is not available: ${status.summary}.`
@@ -1403,19 +2466,14 @@ function resolveProviderForCapability(config, explicit, cwd, capability) {
     const status = provider.getStatus(providerConfig, cwd);
     if (status.available) return provider;
   }
-  for (const provider of PROVIDERS) {
+  for (const providerId of IMPLICIT_PROVIDER_FALLBACKS) {
+    const provider = PROVIDER_MAP[providerId];
     if (typeof provider[capability] !== "function") continue;
-    if (!isProviderToolEnabled(
-      provider.id,
-      config.providers?.[provider.id],
-      capability
-    )) {
+    const providerConfig = getEffectiveProviderConfig(config, provider.id);
+    if (!isProviderToolEnabled(provider.id, providerConfig, capability)) {
       continue;
     }
-    const status = provider.getStatus(
-      config.providers?.[provider.id],
-      cwd
-    );
+    const status = provider.getStatus(providerConfig, cwd);
     if (status.available) return provider;
   }
   throw new Error(
@@ -1424,16 +2482,32 @@ function resolveProviderForCapability(config, explicit, cwd, capability) {
 }
 
 // src/types.ts
-var PROVIDER_IDS = ["codex", "exa", "gemini", "parallel", "valyu"];
+var PROVIDER_IDS = [
+  "claude",
+  "codex",
+  "exa",
+  "gemini",
+  "perplexity",
+  "parallel",
+  "valyu"
+];
 
 // src/index.ts
 var DEFAULT_MAX_RESULTS = 5;
 var MAX_ALLOWED_RESULTS = 20;
+var RESEARCH_HEARTBEAT_MS = 15e3;
+var CAPABILITY_TOOL_NAMES = {
+  search: "web_search",
+  contents: "web_contents",
+  answer: "web_answer",
+  research: "web_research"
+};
+var MANAGED_TOOL_NAMES = Object.values(CAPABILITY_TOOL_NAMES);
+var PROVIDER_OVERRIDE_GUIDELINES = [
+  "Do not set provider unless the user asks for one."
+];
 function webProvidersExtension(pi) {
-  registerWebSearchTool(pi);
-  registerWebContentsTool(pi);
-  registerWebAnswerTool(pi);
-  registerWebResearchTool(pi);
+  registerManagedTools(pi);
   pi.registerCommand("web-providers", {
     description: "Configure web search providers",
     handler: async (_args, ctx) => {
@@ -1441,15 +2515,38 @@ function webProvidersExtension(pi) {
         ctx.ui.notify("web-providers requires interactive mode", "error");
         return;
       }
-      await runWebProvidersConfig(ctx);
+      await runWebProvidersConfig(pi, ctx);
     }
   });
+  pi.on("session_start", async (_event, ctx) => {
+    await refreshManagedTools(pi, ctx.cwd, { addAvailable: true });
+  });
+  pi.on("before_agent_start", async (_event, ctx) => {
+    await refreshManagedTools(pi, ctx.cwd, { addAvailable: false });
+  });
+}
+function registerManagedTools(pi, providerIdsByCapability = {}) {
+  registerWebSearchTool(pi, providerIdsByCapability.search ?? PROVIDER_IDS);
+  registerWebContentsTool(
+    pi,
+    providerIdsByCapability.contents ?? getProviderIdsForCapability("contents")
+  );
+  registerWebAnswerTool(
+    pi,
+    providerIdsByCapability.answer ?? getProviderIdsForCapability("answer")
+  );
+  registerWebResearchTool(
+    pi,
+    providerIdsByCapability.research ?? getProviderIdsForCapability("research")
+  );
 }
-function registerWebSearchTool(pi) {
+function registerWebSearchTool(pi, providerIds) {
+  const visibleProviderIds = providerIds.length > 0 ? providerIds : PROVIDER_IDS;
   pi.registerTool({
     name: "web_search",
     label: "Web Search",
-    description: `Search the public web and return results with titles, URLs, and snippets. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} when needed.`,
+    description: `Find likely sources on the public web and return titles, URLs, and snippets. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} when needed.`,
+    promptGuidelines: PROVIDER_OVERRIDE_GUIDELINES,
     parameters: Type.Object({
       query: Type.String({ description: "What to search for on the web" }),
       maxResults: Type.Optional(
@@ -1459,23 +2556,24 @@ function registerWebSearchTool(pi) {
           description: `Maximum number of results to return (default: ${DEFAULT_MAX_RESULTS})`
         })
       ),
-      provider: Type.Optional(
-        StringEnum(PROVIDER_IDS, {
-          description: "Provider override. If omitted, uses the active configured provider or falls back to the first available provider alphabetically."
-        })
+      options: jsonOptionsSchema("Provider-specific search options."),
+      provider: providerEnum(
+        visibleProviderIds,
+        "Provider override. If omitted, uses the active configured provider or falls back to Codex for search when it is not explicitly disabled."
       )
     }),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const config = await loadConfig();
       const provider = resolveProviderChoice(config, params.provider, ctx.cwd);
       const maxResults = clampResults(params.maxResults);
-      const providerConfig = config.providers?.[provider.id];
+      const providerConfig = getEffectiveProviderConfig(config, provider.id);
       if (!providerConfig) {
         throw new Error(`Provider '${provider.id}' is not configured.`);
       }
       const response = await provider.search(
         params.query,
         maxResults,
+        normalizeOptions(params.options),
         providerConfig,
         {
           cwd: ctx.cwd,
@@ -1524,13 +2622,12 @@ function registerWebSearchTool(pi) {
     }
   });
 }
-function registerWebContentsTool(pi) {
-  const providerIds = getProviderIdsForCapability("contents");
+function registerWebContentsTool(pi, providerIds) {
   if (providerIds.length === 0) return;
   pi.registerTool({
     name: "web_contents",
     label: "Web Contents",
-    description: "Fetch extracted contents for one or more URLs using a configured provider.",
+    description: "Read and extract the main contents of one or more web pages.",
     parameters: Type.Object({
       urls: Type.Array(Type.String({ minLength: 1 }), {
         minItems: 1,
@@ -1542,6 +2639,7 @@ function registerWebContentsTool(pi) {
         "Provider override. If omitted, uses the active configured provider that supports web contents."
       )
     }),
+    promptGuidelines: PROVIDER_OVERRIDE_GUIDELINES,
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       return executeProviderTool({
         capability: "contents",
@@ -1579,13 +2677,12 @@ function registerWebContentsTool(pi) {
     }
   });
 }
-function registerWebAnswerTool(pi) {
-  const providerIds = getProviderIdsForCapability("answer");
+function registerWebAnswerTool(pi, providerIds) {
   if (providerIds.length === 0) return;
   pi.registerTool({
     name: "web_answer",
     label: "Web Answer",
-    description: "Get a provider-generated answer grounded in web results.",
+    description: "Answer a question using web-grounded evidence.",
     parameters: Type.Object({
       query: Type.String({ description: "Question to answer" }),
       options: jsonOptionsSchema("Provider-specific answer options."),
@@ -1594,6 +2691,7 @@ function registerWebAnswerTool(pi) {
         "Provider override. If omitted, uses the active configured provider that supports web answers."
       )
     }),
+    promptGuidelines: PROVIDER_OVERRIDE_GUIDELINES,
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       return executeProviderTool({
         capability: "answer",
@@ -1613,8 +2711,10 @@ function registerWebAnswerTool(pi) {
     renderCall(args, theme) {
       return renderToolCallHeader(
         "web_answer",
-        `"${cleanSingleLine(String(args.query ?? "")).slice(0, 80)}"`,
-        [`provider=${String(args.provider ?? "auto")}`],
+        formatQuotedPreview(String(args.query ?? "")),
+        [
+          `provider=${String(args.provider ?? "auto")}`
+        ],
         theme
       );
     },
@@ -1629,13 +2729,12 @@ function registerWebAnswerTool(pi) {
     }
   });
 }
-function registerWebResearchTool(pi) {
-  const providerIds = getProviderIdsForCapability("research");
+function registerWebResearchTool(pi, providerIds) {
   if (providerIds.length === 0) return;
   pi.registerTool({
     name: "web_research",
     label: "Web Research",
-    description: "Run a longer-form research task using a provider that supports research.",
+    description: "Investigate a topic across web sources and produce a longer report.",
     parameters: Type.Object({
       input: Type.String({ description: "Research brief or question" }),
       options: jsonOptionsSchema("Provider-specific research options."),
@@ -1644,6 +2743,7 @@ function registerWebResearchTool(pi) {
         "Provider override. If omitted, uses the active configured provider that supports research."
       )
     }),
+    promptGuidelines: PROVIDER_OVERRIDE_GUIDELINES,
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       return executeProviderTool({
         capability: "research",
@@ -1663,8 +2763,10 @@ function registerWebResearchTool(pi) {
     renderCall(args, theme) {
       return renderToolCallHeader(
         "web_research",
-        `"${cleanSingleLine(String(args.input ?? "")).slice(0, 80)}"`,
-        [`provider=${String(args.provider ?? "auto")}`],
+        formatQuotedPreview(String(args.input ?? "")),
+        [
+          `provider=${String(args.provider ?? "auto")}`
+        ],
         theme
       );
     },
@@ -1679,7 +2781,7 @@ function registerWebResearchTool(pi) {
     }
   });
 }
-async function runWebProvidersConfig(ctx) {
+async function runWebProvidersConfig(pi, ctx) {
   const config = await loadConfig();
   const activeProvider = await getPreferredProvider(ctx.cwd);
   await ctx.ui.custom(
@@ -1692,6 +2794,60 @@ async function runWebProvidersConfig(ctx) {
       activeProvider
     )
   );
+  await refreshManagedTools(pi, ctx.cwd, { addAvailable: true });
+}
+function getAvailableProviderIdsForCapability(config, cwd, capability) {
+  const providerIds = [];
+  for (const providerId of getProviderIdsForCapability(capability)) {
+    try {
+      resolveProviderForCapability(config, providerId, cwd, capability);
+      providerIds.push(providerId);
+    } catch {
+    }
+  }
+  return providerIds;
+}
+function getAvailableManagedToolNames(config, cwd) {
+  return Object.keys(CAPABILITY_TOOL_NAMES).filter(
+    (capability) => getAvailableProviderIdsForCapability(config, cwd, capability).length > 0
+  ).map((capability) => CAPABILITY_TOOL_NAMES[capability]);
+}
+function getSyncedActiveTools(config, cwd, activeToolNames, options) {
+  const availableToolNames = new Set(getAvailableManagedToolNames(config, cwd));
+  const nextActiveTools = new Set(activeToolNames);
+  for (const toolName of MANAGED_TOOL_NAMES) {
+    if (availableToolNames.has(toolName)) {
+      if (options.addAvailable) {
+        nextActiveTools.add(toolName);
+      }
+      continue;
+    }
+    nextActiveTools.delete(toolName);
+  }
+  return nextActiveTools;
+}
+async function refreshManagedTools(pi, cwd, options) {
+  const config = await loadConfig();
+  const nextActiveTools = getSyncedActiveTools(
+    config,
+    cwd,
+    pi.getActiveTools(),
+    options
+  );
+  registerManagedTools(pi, {
+    search: getAvailableProviderIdsForCapability(config, cwd, "search"),
+    contents: getAvailableProviderIdsForCapability(config, cwd, "contents"),
+    answer: getAvailableProviderIdsForCapability(config, cwd, "answer"),
+    research: getAvailableProviderIdsForCapability(config, cwd, "research")
+  });
+  await syncManagedToolAvailability(pi, nextActiveTools);
+}
+async function syncManagedToolAvailability(pi, nextActiveTools) {
+  const activeTools = pi.getActiveTools();
+  const changed = activeTools.length !== nextActiveTools.size || activeTools.some((toolName) => !nextActiveTools.has(toolName));
+  if (changed) {
+    pi.setActiveTools(Array.from(nextActiveTools));
+  }
 }
 function getProviderIdsForCapability(capability) {
   return PROVIDERS.filter(
@@ -1703,15 +2859,21 @@ function providerEnum(providerIds, description) {
     return Type.Optional(Type.Literal(providerIds[0], { description }));
   }
   return Type.Optional(
-    Type.Union(providerIds.map((id) => Type.Literal(id)), { description })
+    Type.Union(
+      providerIds.map((id) => Type.Literal(id)),
+      { description }
+    )
   );
 }
 function jsonOptionsSchema(description) {
   return Type.Optional(
-    Type.Object({}, {
-      additionalProperties: true,
-      description
-    })
+    Type.Object(
+      {},
+      {
+        additionalProperties: true,
+        description
+      }
+    )
   );
 }
 async function executeProviderTool({
@@ -1729,36 +2891,74 @@ async function executeProviderTool({
     ctx.cwd,
     capability
   );
-  const providerConfig = config.providers?.[provider.id];
+  const providerConfig = getEffectiveProviderConfig(config, provider.id);
   if (!providerConfig) {
     throw new Error(`Provider '${provider.id}' is not configured.`);
   }
-  const response = await invoke(
-    provider,
-    providerConfig,
-    {
+  const progress = createToolProgressReporter(
+    capability,
+    provider.id,
+    onUpdate
+  );
+  let response;
+  try {
+    response = await invoke(provider, providerConfig, {
       cwd: ctx.cwd,
       signal: signal ?? void 0,
-      onProgress: (message) => onUpdate?.({
-        content: [{ type: "text", text: message }],
-        details: {}
-      })
-    }
-  );
+      onProgress: progress.report
+    });
+  } finally {
+    progress.stop();
+  }
   const details = {
     tool: `web_${capability}`,
     provider: response.provider,
     summary: response.summary,
     itemCount: response.itemCount
   };
+  const text = await truncateAndSave(response.text, capability);
   return {
-    content: [{ type: "text", text: response.text }],
+    content: [{ type: "text", text }],
     details
   };
 }
 function normalizeOptions(value) {
   return isJsonObject(value) ? value : void 0;
 }
+function createToolProgressReporter(capability, providerId, onUpdate) {
+  if (!onUpdate) {
+    return { report: void 0, stop: () => {
+    } };
+  }
+  const emit = (message) => onUpdate({
+    content: [{ type: "text", text: message }],
+    details: {}
+  });
+  const startedAt = Date.now();
+  let lastUpdateAt = startedAt;
+  let timer;
+  if (capability === "research") {
+    timer = setInterval(() => {
+      if (Date.now() - lastUpdateAt < RESEARCH_HEARTBEAT_MS) {
+        return;
+      }
+      const elapsed = formatElapsed2(Date.now() - startedAt);
+      emit(`web_research still running via ${providerId} (${elapsed} elapsed)`);
+      lastUpdateAt = Date.now();
+    }, RESEARCH_HEARTBEAT_MS);
+  }
+  return {
+    report: (message) => {
+      lastUpdateAt = Date.now();
+      emit(message);
+    },
+    stop: () => {
+      if (timer) {
+        clearInterval(timer);
+      }
+    }
+  };
+}
 function renderToolCallHeader(toolName, primary, details, theme) {
   return {
     invalidate() {
@@ -1829,6 +3029,30 @@ function buildProviderMenuOptions(providerId) {
       values
     });
   };
+  if (providerId === "claude") {
+    pushText(
+      "model",
+      "Model",
+      "Optional Claude model override. Leave empty to use the local default."
+    );
+    pushValues(
+      "claudeEffort",
+      "Effort",
+      "How much effort Claude should use. 'default' uses the SDK default.",
+      ["default", "low", "medium", "high", "max"]
+    );
+    pushText(
+      "claudeMaxTurns",
+      "Max turns",
+      "Optional maximum number of Claude turns. Leave empty to use the SDK default."
+    );
+    pushText(
+      "claudePathToExecutable",
+      "Executable path",
+      "Optional path to the Claude Code executable. Leave empty to use the bundled/default executable."
+    );
+    return options;
+  }
   if (providerId === "codex") {
     pushText(
       "model",
@@ -1912,6 +3136,11 @@ function buildProviderMenuOptions(providerId) {
       "Search model",
       "Model used for Gemini search interactions."
     );
+    pushText(
+      "geminiContentsModel",
+      "Contents model",
+      "Model used for Gemini URL content extraction via URL Context."
+    );
     pushText(
       "geminiAnswerModel",
       "Answer model",
@@ -1924,6 +3153,9 @@ function buildProviderMenuOptions(providerId) {
     );
     return options;
   }
+  if (providerId === "perplexity") {
+    return options;
+  }
   if (providerId === "parallel") {
     pushValues(
       "parallelSearchMode",
@@ -1983,17 +3215,24 @@ var WebProvidersSettingsView = class {
     }
     const lines = [];
     const providerItems = this.buildProviderSectionItems();
-    lines.push(...this.renderSection(width, "Provider", "provider", providerItems));
+    lines.push(
+      ...this.renderSection(width, "Provider", "provider", providerItems)
+    );
     lines.push("");
     const toolItems = this.buildToolSectionItems();
     lines.push(...this.renderSection(width, "Tools", "tools", toolItems));
     lines.push("");
     const configItems = this.buildConfigSectionItems();
-    lines.push(...this.renderSection(width, "Provider config", "config", configItems));
+    lines.push(
+      ...this.renderSection(width, "Provider config", "config", configItems)
+    );
     const selected = this.getSelectedEntry();
     if (selected) {
       lines.push("");
-      for (const line of wrapTextWithAnsi(selected.description, Math.max(10, width - 2))) {
+      for (const line of wrapTextWithAnsi(
+        selected.description,
+        Math.max(10, width - 2)
+      )) {
         lines.push(truncateToWidth(this.theme.fg("dim", line), width));
       }
     }
@@ -2090,10 +3329,13 @@ var WebProvidersSettingsView = class {
     }
     if (option.kind === "text") {
       const key = option.key;
-      const currentValue = key === "model" || key === "additionalDirectories" ? getCodexTextSettingValue(
+      const currentValue = this.activeProvider === "claude" && (key === "model" || key === "claudePathToExecutable" || key === "claudeMaxTurns") ? getClaudeTextSettingValue(
         providerConfig,
         key
-      ) : key === "geminiSearchModel" || key === "geminiAnswerModel" || key === "geminiResearchAgent" ? getGeminiTextSettingValue(
+      ) : key === "model" || key === "additionalDirectories" ? getCodexTextSettingValue(
+        providerConfig,
+        key
+      ) : key === "geminiSearchModel" || key === "geminiContentsModel" || key === "geminiAnswerModel" || key === "geminiResearchAgent" ? getGeminiTextSettingValue(
         providerConfig,
         key
       ) : getProviderStringValue(
@@ -2132,7 +3374,7 @@ var WebProvidersSettingsView = class {
       "tools",
       "config"
     ];
-    let index = sections.indexOf(this.activeSection);
+    const index = sections.indexOf(this.activeSection);
     for (let offset = 1; offset <= sections.length; offset++) {
       const next = sections[(index + offset * direction + sections.length) % sections.length];
       if (this.getSectionEntries(next).length > 0) {
@@ -2221,13 +3463,19 @@ var WebProvidersSettingsView = class {
     if (id === "apiKey" || id === "baseUrl") {
       return getProviderStringValue(providerConfig, id);
     }
+    if (this.activeProvider === "claude" && (id === "model" || id === "claudePathToExecutable" || id === "claudeMaxTurns")) {
+      return getClaudeTextSettingValue(
+        providerConfig,
+        id
+      );
+    }
     if (id === "model" || id === "additionalDirectories") {
       return getCodexTextSettingValue(
         providerConfig,
         id
       );
     }
-    if (id === "geminiSearchModel" || id === "geminiAnswerModel" || id === "geminiResearchAgent") {
+    if (id === "geminiSearchModel" || id === "geminiContentsModel" || id === "geminiAnswerModel" || id === "geminiResearchAgent") {
       return getGeminiTextSettingValue(
         providerConfig,
         id
@@ -2268,6 +3516,11 @@ var WebProvidersSettingsView = class {
       }
       if (id === "apiKey" || id === "baseUrl") {
         assignOptionalString(providerConfig, id, value);
+      } else if (this.activeProvider === "claude" && applyClaudeSettingChange(
+        providerConfig,
+        id,
+        value
+      )) {
       } else if (this.activeProvider === "codex" && applyCodexSettingChange(
         providerConfig,
         id,
@@ -2408,6 +3661,12 @@ function getProviderStringValue(config, key) {
   return typeof value === "string" ? value : void 0;
 }
 function getProviderChoiceValue(providerId, config, key) {
+  if (providerId === "claude") {
+    const defaults = config?.defaults;
+    if (key === "claudeEffort") {
+      return typeof defaults?.effort === "string" ? defaults.effort : "default";
+    }
+  }
   if (providerId === "codex") {
     const defaults = config?.defaults;
     if (key === "networkAccessEnabled" || key === "webSearchEnabled") {
@@ -2462,6 +3721,17 @@ function getProviderChoiceValue(providerId, config, key) {
   }
   throw new Error(`Unsupported choice setting '${key}' for '${providerId}'.`);
 }
+function getClaudeTextSettingValue(config, key) {
+  if (key === "claudePathToExecutable") {
+    return config?.pathToClaudeCodeExecutable;
+  }
+  const defaults = config?.defaults;
+  if (!defaults) return void 0;
+  if (key === "claudeMaxTurns") {
+    return typeof defaults.maxTurns === "number" ? String(defaults.maxTurns) : void 0;
+  }
+  return defaults.model;
+}
 function getCodexTextSettingValue(config, key) {
   const defaults = config?.defaults;
   if (!defaults) return void 0;
@@ -2474,6 +3744,7 @@ function getGeminiTextSettingValue(config, key) {
   const defaults = config?.defaults;
   if (!defaults) return void 0;
   if (key === "geminiSearchModel") return defaults.searchModel;
+  if (key === "geminiContentsModel") return defaults.contentsModel;
   if (key === "geminiAnswerModel") return defaults.answerModel;
   return defaults.researchAgent;
 }
@@ -2485,6 +3756,51 @@ function assignOptionalString(target, key, value) {
     target[key] = trimmed;
   }
 }
+function applyClaudeSettingChange(target, key, value) {
+  target.defaults ??= {};
+  switch (key) {
+    case "model":
+      assignOptionalString(
+        target.defaults,
+        "model",
+        value
+      );
+      cleanupClaudeDefaults(target);
+      return true;
+    case "claudePathToExecutable":
+      assignOptionalString(
+        target,
+        "pathToClaudeCodeExecutable",
+        value
+      );
+      cleanupClaudeDefaults(target);
+      return true;
+    case "claudeMaxTurns": {
+      const trimmed = value.trim();
+      if (!trimmed) {
+        delete target.defaults.maxTurns;
+      } else {
+        const parsed = Number(trimmed);
+        if (!Number.isInteger(parsed) || parsed < 1) {
+          throw new Error("Claude max turns must be a positive integer.");
+        }
+        target.defaults.maxTurns = parsed;
+      }
+      cleanupClaudeDefaults(target);
+      return true;
+    }
+    case "claudeEffort":
+      if (value === "default") {
+        delete target.defaults.effort;
+      } else {
+        target.defaults.effort = value;
+      }
+      cleanupClaudeDefaults(target);
+      return true;
+    default:
+      return false;
+  }
+}
 function applyCodexSettingChange(target, key, value) {
   target.defaults ??= {};
   switch (key) {
@@ -2600,6 +3916,14 @@ function applyGeminiSettingChange(target, key, value) {
       );
       cleanupGeminiDefaults(target);
       return true;
+    case "geminiContentsModel":
+      assignOptionalString(
+        target.defaults,
+        "contentsModel",
+        value
+      );
+      cleanupGeminiDefaults(target);
+      return true;
     case "geminiAnswerModel":
       assignOptionalString(
         target.defaults,
@@ -2653,6 +3977,11 @@ function applyParallelSettingChange(target, key, value) {
       return false;
   }
 }
+function cleanupClaudeDefaults(target) {
+  if (target.defaults && Object.keys(target.defaults).length === 0) {
+    delete target.defaults;
+  }
+}
 function cleanupCodexDefaults(target) {
   if (target.defaults && Object.keys(target.defaults).length === 0) {
     delete target.defaults;
@@ -2699,9 +4028,9 @@ function renderCallHeader(params, theme) {
     },
     render(width) {
       let header = theme.fg("toolTitle", theme.bold("web_search"));
-      const query = cleanSingleLine(String(params.query ?? "")).trim();
-      if (query.length > 0) {
-        header += ` ${theme.fg("accent", `"${query.slice(0, 80)}"`)} `;
+      const query2 = cleanSingleLine(String(params.query ?? "")).trim();
+      if (query2.length > 0) {
+        header += ` ${theme.fg("accent", formatQuotedPreview(query2))} `;
       }
       const lines = [];
       const headerLine = truncateToWidth(header.trimEnd(), width);
@@ -2758,6 +4087,18 @@ function getExpandHint() {
 function cleanSingleLine(text) {
   return text.replace(/\s+/g, " ").trim();
 }
+function formatQuotedPreview(text, maxLength = 80) {
+  return `"${truncateInline(cleanSingleLine(text), maxLength)}"`;
+}
+function formatElapsed2(ms) {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1e3));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${totalSeconds}s`;
+}
 function formatSearchResponse(response) {
   if (response.results.length === 0) {
     return "No results found.";
@@ -2779,9 +4120,9 @@ async function truncateAndSave(text, prefix) {
     maxBytes: DEFAULT_MAX_BYTES
   });
   if (!truncation.truncated) return truncation.content;
-  const dir = join2(tmpdir(), `pi-web-providers-${prefix}-${Date.now()}`);
+  const dir = join4(tmpdir(), `pi-web-providers-${prefix}-${Date.now()}`);
   await mkdir2(dir, { recursive: true });
-  const fullPath = join2(dir, "output.txt");
+  const fullPath = join4(dir, "output.txt");
   await writeFile2(fullPath, text, "utf-8");
   return truncation.content + `
 
@@ -2792,7 +4133,11 @@ function truncateInline(text, maxLength) {
   return `${text.slice(0, maxLength - 1)}\u2026`;
 }
 var __test__ = {
+  executeProviderTool,
   extractTextContent,
+  getAvailableManagedToolNames,
+  getAvailableProviderIdsForCapability,
+  getSyncedActiveTools,
   renderCallHeader,
   renderCollapsedSearchSummary
 };