opencandle 0.6.0 → 0.8.0

package/src/onboarding/providers.ts

@@ -1,23 +1,33 @@
-// Provider registry — single source of truth for OpenCandle's credentialed
-// third-party data providers. Every setup pathway iterates this registry:
+// Provider registry — single source of truth for OpenCandle's third-party
+// data providers. Every setup/status pathway iterates this registry:
 // first-run startup, the `/connect` command, the `tool_result` credential
-// interception handler, and the gap-note generator all read from here.
+// interception handler, GUI provider rows, doctor checks, and gap-note
+// generation all read from here.
 //
-// Adding a new credentialed provider is a two-step change: add its `ProviderId`
-// to the literal union below, and add its descriptor to the `PROVIDERS` array.
-// The `satisfies` check ensures TypeScript fails the build if the union and
-// the array ever disagree.
+// Adding a new provider is a two-step change: add its id to the relevant
+// literal union below, and add its descriptor to the `PROVIDERS` array. The
+// `satisfies` and exhaustiveness checks keep the registry and id unions aligned.
 
 import { getConfig, loadFileConfig } from "../config.js";
 
-export type ProviderId = "alpha_vantage" | "fred" | "finnhub" | "brave" | "exa";
+export type ApiKeyProviderId = "alpha_vantage" | "fred" | "finnhub" | "brave" | "exa";
+export type ExternalToolProviderId = "twitter" | "reddit";
+export type PublicHttpProviderId = "yahoo";
+export type ProviderId = ApiKeyProviderId | ExternalToolProviderId | PublicHttpProviderId;
 
-export type ProviderCategory = "fundamentals" | "macro" | "news" | "web_search";
+export type ProviderCategory =
+  | "fundamentals"
+  | "macro"
+  | "news"
+  | "web_search"
+  | "sentiment"
+  | "market";
 
 export type ProviderTier = "hard" | "soft";
 
-export interface ProviderDescriptor {
+interface BaseProviderDescriptor {
   readonly id: ProviderId;
+  readonly kind: "api-key" | "external-tool" | "public-http";
   readonly displayName: string;
   readonly category: ProviderCategory;
   /**
@@ -30,11 +40,6 @@ export interface ProviderDescriptor {
   readonly tier: ProviderTier;
   /** Lowercase friendly aliases accepted by `/connect` in addition to the id. */
   readonly aliases: readonly string[];
-  readonly signupUrl: string;
-  readonly freeTier: boolean;
-  readonly envVar: string;
-  /** Nested key path into `OpenCandleFileConfig` where the key is persisted. */
-  readonly configPath: readonly string[];
   readonly unlocks: readonly string[];
   /**
    * Human copy describing the degraded experience when missing, or `null`
@@ -45,11 +50,43 @@ export interface ProviderDescriptor {
   readonly instructionsHint: string;
 }
 
+export interface ApiKeyProviderDescriptor extends BaseProviderDescriptor {
+  readonly id: ApiKeyProviderId;
+  readonly kind: "api-key";
+  readonly signupUrl: string;
+  readonly freeTier: boolean;
+  readonly envVar: string;
+  /** Nested key path into `OpenCandleFileConfig` where the key is persisted. */
+  readonly configPath: readonly string[];
+}
+
+export interface ExternalToolProviderDescriptor extends BaseProviderDescriptor {
+  readonly id: ExternalToolProviderId;
+  readonly kind: "external-tool";
+  readonly binary: string;
+  readonly installCmd: string;
+  readonly sessionSource: "browser-cookies";
+  readonly supportedBrowsers?: readonly string[];
+  readonly sessionProbeArgs?: readonly string[];
+}
+
+export interface PublicHttpProviderDescriptor extends BaseProviderDescriptor {
+  readonly id: PublicHttpProviderId;
+  readonly kind: "public-http";
+  readonly probeUrl: string;
+}
+
+export type ProviderDescriptor =
+  | ApiKeyProviderDescriptor
+  | ExternalToolProviderDescriptor
+  | PublicHttpProviderDescriptor;
+
 // Declaration order matters: picker display order, per-workflow prompt priority,
 // getProvidersByCategory/getProvidersByTier iteration order.
 export const PROVIDERS = [
   {
     id: "alpha_vantage",
+    kind: "api-key",
     displayName: "Alpha Vantage",
     category: "fundamentals",
     tier: "hard",
@@ -70,6 +107,7 @@ export const PROVIDERS = [
   },
   {
     id: "fred",
+    kind: "api-key",
     displayName: "FRED",
     category: "macro",
     tier: "hard",
@@ -85,6 +123,7 @@ export const PROVIDERS = [
   },
   {
     id: "finnhub",
+    kind: "api-key",
     displayName: "Finnhub",
     category: "news",
     tier: "soft",
@@ -104,6 +143,7 @@ export const PROVIDERS = [
   },
   {
     id: "brave",
+    kind: "api-key",
     displayName: "Brave Search",
     category: "web_search",
     tier: "soft",
@@ -123,6 +163,7 @@ export const PROVIDERS = [
   },
   {
     id: "exa",
+    kind: "api-key",
     displayName: "Exa",
     category: "web_search",
     tier: "soft",
@@ -147,8 +188,64 @@ export const PROVIDERS = [
     snoozeDurationDays: 7,
     instructionsHint: "Paid with free tier, signup opens in your browser",
   },
+  {
+    id: "yahoo",
+    kind: "public-http",
+    displayName: "Yahoo Finance",
+    category: "market",
+    tier: "hard",
+    aliases: ["yahoo", "yahoo-finance", "market-data", "options"],
+    probeUrl: "https://query1.finance.yahoo.com/v8/finance/chart/SPY?interval=1d&range=1d",
+    unlocks: ["quotes", "historical prices", "option chains", "market data"],
+    fallbackDescription: null,
+    snoozeDurationDays: 7,
+    instructionsHint: "No account needed; OpenCandle checks public Yahoo Finance reachability",
+  },
+  {
+    id: "twitter",
+    kind: "external-tool",
+    displayName: "X / Twitter",
+    category: "sentiment",
+    tier: "soft",
+    aliases: ["twitter", "x", "x-sentiment", "twitter-sentiment"],
+    binary: "twitter",
+    installCmd: "uv tool install twitter-cli",
+    sessionSource: "browser-cookies",
+    sessionProbeArgs: ["feed", "--max", "1", "--json"],
+    supportedBrowsers: ["Chrome", "Arc", "Edge", "Firefox", "Brave"],
+    unlocks: ["X/Twitter sentiment", "recent ticker mentions", "social engagement context"],
+    fallbackDescription:
+      "Sentiment summaries continue with Reddit, web search, and news when X is unavailable",
+    snoozeDurationDays: 7,
+    instructionsHint: "Install twitter-cli and stay logged into x.com in a supported browser",
+  },
+  {
+    id: "reddit",
+    kind: "external-tool",
+    displayName: "Reddit",
+    category: "sentiment",
+    tier: "soft",
+    aliases: ["reddit", "reddit-sentiment", "subreddit"],
+    binary: "rdt",
+    installCmd: "uv tool install rdt-cli",
+    sessionSource: "browser-cookies",
+    supportedBrowsers: ["Chrome", "Arc", "Edge", "Firefox", "Brave"],
+    sessionProbeArgs: ["status", "--json"],
+    unlocks: ["Reddit sentiment", "ticker discussion context", "retail investor discussion"],
+    fallbackDescription:
+      "Sentiment summaries continue with X/Twitter, web search, and news when Reddit is unavailable",
+    snoozeDurationDays: 7,
+    instructionsHint: "Install rdt-cli and stay logged into reddit.com in a supported browser",
+  },
 ] as const satisfies readonly ProviderDescriptor[];
 
+const _providerIdExhaustivenessCheck: Record<
+  | Exclude<ProviderId, (typeof PROVIDERS)[number]["id"]>
+  | Exclude<(typeof PROVIDERS)[number]["id"], ProviderId>,
+  never
+> = {};
+void _providerIdExhaustivenessCheck;
+
 // -----------------------------------------------------------------------------
 // Lookup helpers
 // -----------------------------------------------------------------------------
@@ -169,6 +266,28 @@ export function listAllProviders(): readonly ProviderDescriptor[] {
   return PROVIDERS;
 }
 
+export function isApiKeyProvider(
+  provider: ProviderDescriptor,
+): provider is ApiKeyProviderDescriptor {
+  return provider.kind === "api-key";
+}
+
+export function isExternalToolProvider(
+  provider: ProviderDescriptor,
+): provider is ExternalToolProviderDescriptor {
+  return provider.kind === "external-tool";
+}
+
+export function isPublicHttpProvider(
+  provider: ProviderDescriptor,
+): provider is PublicHttpProviderDescriptor {
+  return provider.kind === "public-http";
+}
+
+export function listApiKeyProviders(): readonly ApiKeyProviderDescriptor[] {
+  return (PROVIDERS as readonly ProviderDescriptor[]).filter(isApiKeyProvider);
+}
+
 export function getProvider(id: ProviderId): ProviderDescriptor {
   const found = byId().get(id);
   if (!found) {
@@ -209,7 +328,7 @@ function readConfigValueByPath(
 // `hasCredential` reads from `getConfig()` so that tests mocking `getConfig`
 // see a consistent view; `getCredentialSource` reads `process.env` +
 // `loadFileConfig` directly because it needs to distinguish env from file.
-const CONFIG_FIELD_BY_ID: Record<ProviderId, keyof ReturnType<typeof getConfig>> = {
+const CONFIG_FIELD_BY_ID: Record<ApiKeyProviderId, keyof ReturnType<typeof getConfig>> = {
   alpha_vantage: "alphaVantageApiKey",
   fred: "fredApiKey",
   finnhub: "finnhubApiKey",
@@ -218,7 +337,9 @@ const CONFIG_FIELD_BY_ID: Record<ProviderId, keyof ReturnType<typeof getConfig>>
 };
 
 export function hasCredential(id: ProviderId): boolean {
-  const field = CONFIG_FIELD_BY_ID[id];
+  const descriptor = getProvider(id);
+  if (!isApiKeyProvider(descriptor)) return false;
+  const field = CONFIG_FIELD_BY_ID[descriptor.id];
   const value = getConfig()[field];
   return typeof value === "string" && value.length > 0;
 }
@@ -231,6 +352,8 @@ export function getCredential(
   id: ProviderId,
 ): { source: "env" | "file"; value: string } | { source: "absent"; value?: undefined } {
   const descriptor = getProvider(id);
+  if (!isApiKeyProvider(descriptor)) return { source: "absent" };
+
   const envValue = process.env[descriptor.envVar];
   if (envValue && envValue.length > 0) return { source: "env", value: envValue };
 
@@ -265,7 +388,14 @@ export function resolveProviderFromArgument(
   // 3. Category match: if the needle matches a category name, return the
   //    providers in that category. One match → single descriptor. Multiple
   //    matches → array (triggers the sub-picker in the /connect handler).
-  const categories: readonly ProviderCategory[] = ["fundamentals", "macro", "news", "web_search"];
+  const categories: readonly ProviderCategory[] = [
+    "fundamentals",
+    "macro",
+    "news",
+    "web_search",
+    "sentiment",
+    "market",
+  ];
   const normalizedCategory = needle.replace("-", "_");
   if ((categories as readonly string[]).includes(normalizedCategory)) {
     const group = getProvidersByCategory(normalizedCategory as ProviderCategory);

package/src/onboarding/state.ts

@@ -155,6 +155,15 @@ export function markProviderNeverAsk(state: OnboardingState, id: ProviderId): On
   };
 }
 
+export function clearProviderOnboardingEntry(
+  state: OnboardingState,
+  id: ProviderId,
+): OnboardingState {
+  const providers = { ...state.providers };
+  delete providers[id];
+  return { ...state, providers };
+}
+
 export function markWelcomeShown(state: OnboardingState): OnboardingState {
   return { ...state, welcomeShownAt: nowIso() };
 }

package/src/onboarding/tool-tags.ts

@@ -22,6 +22,7 @@ import type { ProviderId } from "./providers.js";
 // -----------------------------------------------------------------------------
 
 export type CredentialRequiredReason = "missing" | "stale";
+export type ExternalToolRequiredReason = "not_installed" | "session_missing" | "session_stale";
 
 export interface CredentialRequiredTagFields {
   provider: ProviderId;
@@ -48,11 +49,20 @@ export interface ConnectedTagFields {
   provider: ProviderId;
 }
 
+export interface ExternalToolRequiredTagFields {
+  provider: ProviderId;
+  reason: ExternalToolRequiredReason;
+  installCmd: string;
+  loginCmd?: string;
+  fallback: string | null;
+}
+
 export type ParsedTag =
   | ({ kind: "credential_required" } & CredentialRequiredTagFields)
   | ({ kind: "soft_degraded" } & SoftDegradedTagFields)
   | ({ kind: "skipped" } & SkippedTagFields)
-  | ({ kind: "connected" } & ConnectedTagFields);
+  | ({ kind: "connected" } & ConnectedTagFields)
+  | ({ kind: "external_tool_required" } & ExternalToolRequiredTagFields);
 
 // -----------------------------------------------------------------------------
 // Builders
@@ -106,12 +116,24 @@ export function buildConnectedTag(fields: ConnectedTagFields): string {
   return `[OPENCANDLE_CONNECTED provider=${fields.provider}]`;
 }
 
+export function buildExternalToolRequiredTag(fields: ExternalToolRequiredTagFields): string {
+  const parts: string[] = [
+    "[OPENCANDLE_EXTERNAL_TOOL_REQUIRED",
+    formatField("provider", fields.provider),
+    formatField("reason", fields.reason),
+    `installCmd=${quote(fields.installCmd)}`,
+    formatField("fallback", fields.fallback ?? "none"),
+  ];
+  if (fields.loginCmd) parts.push(`loginCmd=${quote(fields.loginCmd)}`);
+  return `${parts.join(" ")}]`;
+}
+
 // -----------------------------------------------------------------------------
 // Parser
 // -----------------------------------------------------------------------------
 
 const TAG_LINE_REGEX =
-  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED)([^\]]*)\]/;
+  /\[OPENCANDLE_(CREDENTIAL_REQUIRED|SOFT_DEGRADED|SKIPPED|CONNECTED|EXTERNAL_TOOL_REQUIRED)([^\]]*)\]/;
 
 function parseFields(raw: string): Record<string, string> {
   // Split on `key=value` pairs, respecting quoted values.
@@ -195,6 +217,27 @@ export function parseToolTag(text: string): ParsedTag | undefined {
       return { kind: "connected", provider: provider as ProviderId };
     }
 
+    case "EXTERNAL_TOOL_REQUIRED": {
+      const { provider, reason, installCmd, loginCmd, fallback } = fields;
+      if (
+        !provider ||
+        (reason !== "not_installed" &&
+          reason !== "session_missing" &&
+          reason !== "session_stale") ||
+        !installCmd
+      ) {
+        return undefined;
+      }
+      return {
+        kind: "external_tool_required",
+        provider: provider as ProviderId,
+        reason,
+        installCmd,
+        loginCmd,
+        fallback: fallback === undefined || fallback === "none" ? null : fallback,
+      };
+    }
+
     default:
       return undefined;
   }

package/src/onboarding/validation.ts

@@ -20,7 +20,7 @@
 // All validators share a 5-second timeout via `AbortSignal.timeout` so the
 // connect flow cannot hang if a provider is unreachable.
 
-import type { ProviderId } from "./providers.js";
+import type { ApiKeyProviderId } from "./providers.js";
 
 const VALIDATION_TIMEOUT_MS = 5_000;
 
@@ -107,7 +107,7 @@ function classifyAlphaVantageBody(body: string): ValidationResult | undefined {
  * touch the config file, onboarding state, or any in-memory cache.
  */
 export async function validateCredential(
-  providerId: ProviderId,
+  providerId: ApiKeyProviderId,
   key: string,
 ): Promise<ValidationResult> {
   switch (providerId) {

package/src/pi/opencandle-extension.ts

@@ -44,7 +44,6 @@ import type {
 import { SessionCoordinator } from "../runtime/session-coordinator.js";
 import { generateSessionTitle } from "../runtime/session-title.js";
 import { registerAskUserTool } from "../tools/interaction/ask-user.js";
-import { registerTwitterLoginTool } from "../tools/interaction/twitter-login.js";
 import type { AskUserHandler } from "../types/index.js";
 import {
   buildCompareAssetsWorkflowDefinition,
@@ -105,11 +104,10 @@ export default function openCandleExtension(
   let sessionTitleAttempted = false;
 
   // Register tools
-  for (const tool of getOpenCandleToolDefinitions()) {
+  for (const tool of getOpenCandleToolDefinitions({ askUserHandler: options?.askUserHandler })) {
     pi.registerTool(tool);
   }
   registerAskUserTool(pi, options?.askUserHandler);
-  registerTwitterLoginTool(pi);
 
   // /analyze command
   pi.registerCommand("analyze", {
@@ -144,11 +142,10 @@ export default function openCandleExtension(
   // `/connect <alias|id|category>` routes to a specific provider (or a
   // sub-picker for multi-provider categories like "search").
   pi.registerCommand("connect", {
-    description: "Connect a data provider (Alpha Vantage, FRED, Finnhub, Brave, Exa)",
+    description: "Connect an API-key data provider (Alpha Vantage, FRED, Finnhub, Brave, Exa)",
     handler: async (args, ctx) => {
-      const { listAllProviders, resolveProviderFromArgument, hasCredential } = await import(
-        "../onboarding/providers.js"
-      );
+      const { listApiKeyProviders, resolveProviderFromArgument, hasCredential, isApiKeyProvider } =
+        await import("../onboarding/providers.js");
 
       const formatState = (id: ProviderId): string => {
         const state = loadOnboardingState().providers[id];
@@ -178,11 +175,11 @@ export default function openCandleExtension(
 
       if (trimmed === "") {
         // Bare /connect → full picker.
-        targetId = await pickProvider(listAllProviders());
+        targetId = await pickProvider(listApiKeyProviders());
       } else {
         const resolved = resolveProviderFromArgument(trimmed);
         if (!resolved) {
-          const all = listAllProviders()
+          const all = listApiKeyProviders()
             .map((p) => `  ${p.displayName} (${p.aliases.join(", ")})`)
             .join("\n");
           ctx.ui.notify(`Unknown provider: "${trimmed}". Available:\n${all}`, "warning");
@@ -190,9 +187,25 @@ export default function openCandleExtension(
         }
         if (Array.isArray(resolved)) {
           // Multi-provider category — show a sub-picker.
-          targetId = await pickProvider(resolved as readonly ReturnType<typeof getProvider>[]);
+          const apiKeyProviders = resolved.filter(isApiKeyProvider);
+          if (apiKeyProviders.length === 0) {
+            ctx.ui.notify(
+              `"${trimmed}" does not use API-key setup. Run opencandle doctor for setup status.`,
+              "warning",
+            );
+            return;
+          }
+          targetId = await pickProvider(apiKeyProviders);
         } else {
-          targetId = (resolved as ReturnType<typeof getProvider>).id;
+          const descriptor = resolved as ReturnType<typeof getProvider>;
+          if (!isApiKeyProvider(descriptor)) {
+            ctx.ui.notify(
+              `${descriptor.displayName} does not use API-key setup. Run opencandle doctor for setup status.`,
+              "warning",
+            );
+            return;
+          }
+          targetId = descriptor.id;
         }
       }
 
@@ -389,15 +402,100 @@ export default function openCandleExtension(
       }
     }
 
-    // Second pass: look for a credential-required tag; on match, run the
-    // interception decision and either replace the tool result or prompt
-    // the user. Only the first credential_required tag in the content list
-    // is acted on — subsequent hard-tier prompts are silenced by the
-    // per-workflow cap at the decision-function level.
+    // Second pass: look for setup-required tags; on match, run the interception
+    // decision and either replace the tool result or prompt the user. Only the
+    // first setup tag in the content list is acted on.
     for (const block of event.content) {
       if (block.type !== "text") continue;
       const parsed = parseToolTag(block.text);
-      if (!parsed || parsed.kind !== "credential_required") continue;
+      if (
+        !parsed ||
+        (parsed.kind !== "credential_required" && parsed.kind !== "external_tool_required")
+      ) {
+        continue;
+      }
+
+      if (parsed.kind === "external_tool_required") {
+        const state = loadOnboardingState();
+        const descriptor = getProvider(parsed.provider);
+        if (state.providers[parsed.provider]?.status === "never_ask") {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `${buildSkippedTag({
+                    provider: parsed.provider,
+                    reason: "credential_not_provided",
+                    remediation: `run ${parsed.installCmd} and ${parsed.loginCmd ?? "rdt login"} to enable ${descriptor.displayName} (silenced)`,
+                    silenced: true,
+                  })}\n\n` +
+                  `${descriptor.displayName} data was not fetched because you previously asked not to be reminded about this provider.`,
+              },
+            ],
+          };
+        }
+        const setupLabel =
+          parsed.reason === "not_installed"
+            ? `Continue after installing ${descriptor.displayName}`
+            : `Continue after logging in to ${descriptor.displayName}`;
+        const skipLabel = `Skip ${descriptor.displayName} once`;
+        const neverLabel = `Always skip ${descriptor.displayName}`;
+        const installOrLogin =
+          parsed.reason === "not_installed"
+            ? `Install command: ${parsed.installCmd}.`
+            : `Login command: ${parsed.loginCmd ?? "rdt login"}.`;
+        const questionBody =
+          `${descriptor.displayName} requires a local external tool before this data can be fetched. ` +
+          `${installOrLogin} How would you like to proceed?`;
+
+        sessionPromptedSet.add(parsed.provider);
+        const promptResult = await promptUser(
+          ctx,
+          {
+            question: questionBody,
+            questionType: "select",
+            options: [setupLabel, skipLabel, neverLabel],
+          },
+          options?.askUserHandler,
+        );
+
+        const answer = promptResult.cancelled ? skipLabel : (promptResult.answer ?? skipLabel);
+        if (answer.startsWith("Always")) {
+          saveOnboardingState(markProviderNeverAsk(state, parsed.provider));
+        }
+
+        if (answer.startsWith("Continue")) {
+          return {
+            content: [
+              {
+                type: "text",
+                text:
+                  `${buildConnectedTag({ provider: parsed.provider })}\n\n` +
+                  `${descriptor.displayName} setup was acknowledged. Re-run the original ${descriptor.displayName} request now; if setup is still unavailable, continue without ${descriptor.displayName} and disclose the source gap.`,
+              },
+            ],
+          };
+        }
+
+        const silenced = answer.startsWith("Always");
+        const remediation = silenced
+          ? `run ${parsed.installCmd} and ${parsed.loginCmd ?? "rdt login"} to enable ${descriptor.displayName} (silenced)`
+          : `run ${parsed.installCmd} and ${parsed.loginCmd ?? "rdt login"} to enable ${descriptor.displayName}`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${buildSkippedTag({
+                provider: parsed.provider,
+                reason: "credential_not_provided",
+                remediation,
+                silenced,
+              })}\n\n${descriptor.displayName} data was omitted per your choice.`,
+            },
+          ],
+        };
+      }
 
       const state = loadOnboardingState();
       const action = resolveCredentialRequired({

package/src/pi/session.ts

@@ -1,4 +1,3 @@
-import "../infra/node-version.js";
 import {
   type AuthStorage,
   type CreateAgentSessionResult,
@@ -10,6 +9,7 @@ import {
   type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { loadEnv } from "../config.js";
+import { assertSupportedNodeVersion } from "../infra/node-version.js";
 import type { AskUserHandler } from "../types/index.js";
 import openCandleExtension from "./opencandle-extension.js";
 
@@ -28,6 +28,7 @@ export interface CreateOpenCandleSessionOptions {
 export async function createOpenCandleSession(
   options: CreateOpenCandleSessionOptions = {},
 ): Promise<CreateAgentSessionResult> {
+  assertSupportedNodeVersion();
   loadEnv();
 
   const cwd = options.cwd ?? process.cwd();

package/src/pi/tool-adapter.ts

@@ -4,6 +4,7 @@ import type { TSchema } from "@sinclair/typebox";
 import { getDefaults } from "../memory/tool-defaults.js";
 import { wrapWithDefaults } from "../runtime/tool-defaults-wrapper.js";
 import { getAllTools } from "../tools/index.js";
+import type { AskUserHandler } from "../types/index.js";
 
 export function agentToolToPiTool<TParams extends TSchema, TDetails>(
   tool: AgentTool<TParams, TDetails>,
@@ -14,14 +15,23 @@ export function agentToolToPiTool<TParams extends TSchema, TDetails>(
     description: tool.description,
     promptSnippet: `${tool.name}: ${tool.description}`,
     parameters: tool.parameters,
-    execute: async (toolCallId, params, signal, onUpdate) => {
-      return tool.execute(toolCallId, params, signal, onUpdate);
+    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+      const executeWithContext = tool.execute as unknown as (
+        id: string,
+        params: unknown,
+        signal: AbortSignal | undefined,
+        onUpdate: unknown,
+        ctx: unknown,
+      ) => ReturnType<typeof tool.execute>;
+      return executeWithContext(toolCallId, params, signal, onUpdate, ctx);
     },
   };
 }
 
-export function getOpenCandleToolDefinitions(): ToolDefinition[] {
-  return getAllTools()
+export function getOpenCandleToolDefinitions(
+  options: { askUserHandler?: AskUserHandler } = {},
+): ToolDefinition[] {
+  return getAllTools(options)
     .map((tool) => ({ tool, defaults: safeGetDefaults(tool.name) }))
     .filter(({ defaults }) => defaults.__enabled !== false)
     .map(({ tool, defaults }) => {

package/src/prompts/context-builder.ts

@@ -251,7 +251,7 @@ const SAFETY_RULES = `## Guidelines
 - For crypto position-sizing prompts, start with a concrete allocation range and dollar amount, then show drawdown impact on the user's portfolio, a sleep test, dollar-cost averaging, rebalancing rules, position caps, tax tracking, reputable custody/exchange considerations, and emergency-fund/high-interest-debt prerequisites. Cite the crypto tool-output date or history period and label sparse or unavailable history instead of implying unsupported precision.
 - For rate-cut market-pricing questions, use get_economic_data for the current Fed funds backdrop and search_web for CME FedWatch / Federal Funds futures probabilities before naming what the market is pricing. Distinguish historical Fed rates from futures-implied expectations.
 - For backtest_strategy results, report strategy return, buy-and-hold return, outperformance, trade count, win rate, and max drawdown. Include risk-adjusted metrics such as Sharpe or Sortino when available; otherwise say they were unavailable. Explain why the strategy worked or failed in the tested regime and discuss trading costs/slippage when the user asks whether the edge is practical. Do not reduce a backtest answer to return-only.
-- For sentiment-only prompts, final answer must include the direction and strength of the sentiment signal, the score scale when available, missing sources, why those missing sources matter for the user's question, the source-coverage risk, low sample counts, and how those gaps downgrade confidence. For ticker-specific sentiment prompts, call get_stock_quote before the final answer and state whether sentiment diverges from price action.
+- For sentiment-only prompts, final answer must include the direction and strength of the sentiment signal, the score scale when available, the key positive and negative drivers behind the signal, representative source evidence, missing sources, why those missing sources matter for the user's question, the source-coverage risk, low sample counts, and how those gaps downgrade confidence. For ticker-specific sentiment prompts, call get_stock_quote before the final answer and state whether sentiment diverges from price action; if quote data is unavailable, say price-action divergence could not be evaluated.
 - Commit to specifics when asked for entries, targets, stops, allocations, or position sizes. Refusal is not an acceptable output shape.
 - Each committal response carries FOUR things: the specific number or range, a reasoning chain naming the data points you used, a confidence band, and an invalidation level (what would break the thesis).
 - Conceptual education prompts are not committal responses. Do not append "Analyst View", "Commitment", "Reasoning Chain", "Confidence Band", or "Invalidation Level" sections when the user asked for an explanation, definition, or learning framework rather than a trade, allocation, or recommendation.