crawlforge-mcp-server 6.0.0 → 6.1.0

package/README.md

@@ -69,7 +69,13 @@ npm install -g crawlforge-mcp-server
 
 ### 2. Setup Your API Key (required)
 
-Every tool requires a CrawlForge API key — new accounts get 1,000 free trial credits to start:
+Every tool requires a CrawlForge API key — new accounts get 1,000 free trial credits to start. The recommended path signs you in through the browser, so the key is never pasted into a terminal (a coding agent can run this for you and relay the URL):
+
+```bash
+crawlforge login
+```
+
+It prints an approval URL; open it, approve, and the key is stored in `~/.crawlforge/config.json`. Then run `crawlforge init` to register the MCP server with your client. Or use the interactive wizard, which also configures your clients:
 
 ```bash
 npx crawlforge-setup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "mcpName": "io.github.mysleekdesigns/crawlforge-mcp-server",
   "description": "CrawlForge MCP Server - Professional Model Context Protocol server with 30 web scraping, crawling, deep-research, and autonomous-extraction tools. Returns clean Markdown and structured JSON for Claude, Cursor, and any MCP client. Defaults to local Ollama for LLM extraction (no API key needed); OpenAI/Anthropic available as opt-in. Includes a unified multi-format scrape tool, an autonomous agent, pre-built site templates, and Camoufox stealth browsing.",
   "main": "server.js",

package/server.js

@@ -5,7 +5,7 @@
 export { isCreatorModeVerified } from './src/core/creatorMode.js';
 
 // Import everything else
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/server";
+import { McpServer, ResourceTemplate, isInputRequiredResult } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import { logger } from "./src/utils/Logger.js";
 import { SearchWebTool } from "./src/tools/search/searchWeb.js";
@@ -107,7 +107,7 @@ if (configErrors.length > 0 && config.server.nodeEnv === 'production') {
 // Create the server
 const server = new McpServer({
   name: "crawlforge",
-  version: "6.0.0",
+  version: "6.1.0",
   description: "Production-ready MCP server with 30 web scraping, crawling, and content processing tools. Features MCP Resources (crawlforge://), Prompts, Sampling fallback, Elicitation, stealth browsing, deep research, structured extraction, embedded JavaScript state extraction, real Google SERP rank tracking, Reddit search via community archives, change tracking, local-LLM extraction via Ollama, unified multi-format scrape, and autonomous agent tool.",
   homepage: "https://www.crawlforge.dev",
   icon: "https://www.crawlforge.dev/icon.png",
@@ -607,12 +607,15 @@ registerToolIfEnabled("crawl_deep", {
     ...REDACT_PII_PARAM
   },
   outputSchema: OUTPUT_SCHEMAS.crawl_deep
-}, withAuth("crawl_deep", async ({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session }) => {
+}, withAuth("crawl_deep", async ({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session }, ctx) => {
     try {
       if (!url) {
         return { content: [{ type: "text", text: "URL parameter is required" }], isError: true };
       }
-      const result = await crawlDeepTool.execute({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session });
+      const result = await crawlDeepTool.execute({ url, max_depth, max_pages, include_patterns, exclude_patterns, follow_external, respect_robots, extract_content, content_max_length, concurrency, enable_link_analysis, link_analysis_options, domain_filter, import_filter_config, session }, ctx);
+      // A confirmation round trip is the SDK's result shape, not a tool payload:
+      // it must reach the transport unwrapped (Phase 4.4).
+      if (isInputRequiredResult(result)) return result;
       return dualOutput(result);
     } catch (error) {
       return { content: [{ type: "text", text: `Crawl failed: ${error.message}` }], isError: true };
@@ -763,12 +766,13 @@ registerToolIfEnabled("extract_structured", {
     ...VERIFY_NUMBERS_PARAM
   },
   outputSchema: OUTPUT_SCHEMAS.extract_structured
-}, withAuth("extract_structured", async (params) => {
+}, withAuth("extract_structured", async (params, ctx) => {
   try {
     // Forward params whole. This wrapper used to destructure a fixed six, which
     // silently dropped respect_robots and user_agent — both declared here and
     // read by the tool, so the G5 override was accepted and ignored.
-    const result = await extractStructuredTool.execute(params);
+    const result = await extractStructuredTool.execute(params, ctx);
+    if (isInputRequiredResult(result)) return result;
     return dualOutput(result);
   } catch (error) {
     return { content: [{ type: "text", text: `Structured extraction failed: ${error.message}` }], isError: true };
@@ -855,9 +859,10 @@ registerToolIfEnabled("batch_scrape", {
     ...MAX_INLINE_CHARS_PARAM,
     ...REDACT_PII_PARAM
   }
-}, withAuth("batch_scrape", async (params) => {
+}, withAuth("batch_scrape", async (params, ctx) => {
     try {
-      const result = await batchScrapeTool.execute(params);
+      const result = await batchScrapeTool.execute(params, ctx);
+      if (isInputRequiredResult(result)) return result;
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Batch scrape failed: ${error.message}` }], isError: true };
@@ -1056,9 +1061,10 @@ registerToolIfEnabled("deep_research", {
     }).optional().describe("Webhook for progress and completion notifications"),
     ...MAX_INLINE_CHARS_PARAM
   }
-}, withAuth("deep_research", async (params) => {
+}, withAuth("deep_research", async (params, ctx) => {
     try {
-      const result = await deepResearchTool.execute(params);
+      const result = await deepResearchTool.execute(params, ctx);
+      if (isInputRequiredResult(result)) return result;
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Deep research failed: ${error.message}` }], isError: true };
@@ -1120,9 +1126,10 @@ registerToolIfEnabled("agent", {
     maxSteps: z.number().min(1).max(10).optional().default(5).describe("Max fetch iterations (hard cap: 10)"),
     maxUrls: z.number().min(1).max(20).optional().default(10).describe("Max URLs to fetch (hard cap: 20)")
   }
-}, withAuth("agent", async (params) => {
+}, withAuth("agent", async (params, ctx) => {
     try {
-      const result = await agentTool.execute(params);
+      const result = await agentTool.execute(params, ctx);
+      if (isInputRequiredResult(result)) return result;
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (error) {
       return { content: [{ type: "text", text: `Agent failed: ${error.message}` }], isError: true };

package/src/cli/commands/login.js

@@ -0,0 +1,176 @@
+/**
+ * login command — browser handoff that stores an API key in ~/.crawlforge/config.json.
+ *
+ * The CLI mints PKCE parameters, prints an approval URL for the human, and polls
+ * the website until the signed-in user approves; the key is delivered once, over
+ * the poll, and never typed into a terminal. This command stores the credential
+ * ONLY — registering the MCP server with a client is `crawlforge init`.
+ */
+import { randomBytes, createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import { existsSync } from 'node:fs';
+import authManager from '../../core/authManager.js';
+import { resolveApiEndpoint } from '../../core/endpointGuard.js';
+
+const POLL_INTERVAL_MS = 3000;
+const MAX_BACKOFF_MS = 30000;
+const MAX_CONSECUTIVE_FAILURES = 10;
+
+export function generateLoginParams() {
+  const codeVerifier = randomBytes(32).toString('base64url');
+  return {
+    sessionId: randomBytes(16).toString('hex'),
+    codeVerifier,
+    codeChallenge: createHash('sha256').update(codeVerifier).digest('base64url'),
+  };
+}
+
+export function buildApprovalUrl(endpoint, params, name) {
+  return `${endpoint}/cli-auth?session_id=${params.sessionId}` +
+    `&code_challenge=${params.codeChallenge}&name=${encodeURIComponent(name)}`;
+}
+
+function loginError(code, message) {
+  const err = new Error(message);
+  err.code = code;
+  return err;
+}
+
+/**
+ * Poll the status endpoint until the key arrives. Resolves with the `complete`
+ * payload; rejects with an error whose `code` names why (CLI_AUTH_TIMEOUT,
+ * CLI_AUTH_VERIFIER_MISMATCH, CLI_AUTH_UNREACHABLE). `sleep` and `now` are
+ * injectable so tests neither wait nor hit the network.
+ */
+export async function pollStatus(fetchImpl, endpoint, params, {
+  intervalMs = POLL_INTERVAL_MS,
+  timeoutMs = 600000,
+  requestTimeoutMs = 30000,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = Date.now,
+} = {}) {
+  const deadline = now() + timeoutMs;
+  let interval = intervalMs;
+  let failures = 0;
+  let lastFailure = '';
+
+  while (now() < deadline) {
+    let response;
+    try {
+      response = await fetchImpl(`${endpoint}/api/auth/cli/status`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ session_id: params.sessionId, code_verifier: params.codeVerifier }),
+        signal: AbortSignal.timeout(requestTimeoutMs),
+      });
+    } catch (err) {
+      response = null;
+      lastFailure = err.message;
+    }
+
+    if (response && response.status === 200) {
+      const body = await response.json();
+      if (body.status === 'complete') return body;
+      if (body.status === 'pending') {
+        failures = 0;
+      } else {
+        failures++;
+        lastFailure = `unexpected status "${body.status}"`;
+      }
+    } else if (response && response.status === 403) {
+      let code = 'CLI_AUTH_FORBIDDEN';
+      try { code = (await response.json()).error?.code || code; } catch { /* keep default */ }
+      throw loginError(code, code === 'CLI_AUTH_VERIFIER_MISMATCH'
+        ? 'The website rejected this session\'s verifier. Run crawlforge login again and open the new URL.'
+        : `The website refused the login session (${code}).`);
+    } else if (response && response.status === 429) {
+      interval = Math.min(interval * 2, MAX_BACKOFF_MS);
+    } else if (response) {
+      failures++;
+      lastFailure = `HTTP ${response.status}`;
+    } else {
+      failures++;
+    }
+
+    if (failures >= MAX_CONSECUTIVE_FAILURES) {
+      throw loginError('CLI_AUTH_UNREACHABLE',
+        `Gave up after ${failures} consecutive failed status checks (last: ${lastFailure}).`);
+    }
+    await sleep(interval);
+  }
+
+  throw loginError('CLI_AUTH_TIMEOUT',
+    `No approval within ${Math.round(timeoutMs / 1000)} seconds. Run crawlforge login again.`);
+}
+
+export function register(program) {
+  program
+    .command('login')
+    .description('Sign in through your browser and store an API key in ~/.crawlforge/config.json (does not touch client configs)')
+    .option('--name <name>', 'Name for the API key the approval creates', `CLI on ${hostname()}`)
+    // Not `--timeout`: the program-level `--timeout <ms>` parses argv first and
+    // would swallow the value, so a subcommand option of that name never gets one.
+    .option('--wait <seconds>', 'How long to wait for approval', '600')
+    .action(async (opts, cmd) => {
+      const json = cmd.parent.opts().json;
+      const out = (msg) => process.stderr.write(msg + '\n');
+      const fail = (code, message) => {
+        if (json) {
+          process.stdout.write(JSON.stringify({ status: 'error', code, message }) + '\n', () => process.exit(1));
+        } else {
+          out('Error: ' + message);
+          process.exit(1);
+        }
+      };
+      process.on('SIGINT', () => fail('CLI_AUTH_CANCELLED', 'Login cancelled.'));
+
+      // resolveApiEndpoint() returns the origin with a trailing slash; strip it
+      // so the approval URL and the status endpoint are not `host//path`.
+      const endpoint = resolveApiEndpoint(process.env.CRAWLFORGE_API_URL || 'https://www.crawlforge.dev').replace(/\/+$/, '');
+      const params = generateLoginParams();
+      const hadConfig = existsSync(authManager.configPath);
+
+      out('Open this URL in your browser and approve the key (session ' + params.sessionId.slice(0, 8) + '):');
+      out('');
+      out('  ' + buildApprovalUrl(endpoint, params, opts.name));
+      out('');
+      out('Waiting for approval… (Ctrl-C to cancel)');
+
+      let result;
+      try {
+        result = await pollStatus(fetch, endpoint, params, {
+          timeoutMs: parseInt(opts.wait, 10) * 1000,
+          requestTimeoutMs: parseInt(process.env.CRAWLFORGE_CLI_TIMEOUT || '30000', 10),
+        });
+      } catch (err) {
+        return fail(err.code || 'CLI_AUTH_FAILED', err.message);
+      }
+
+      const validation = await authManager.validateApiKey(result.api_key);
+      if (!validation.valid) {
+        return fail('CLI_AUTH_KEY_INVALID', 'The delivered API key failed validation: ' + validation.error);
+      }
+      await authManager.saveConfig(result.api_key, validation.userId, validation.email);
+
+      if (json) {
+        const line = JSON.stringify({
+          status: 'complete',
+          email: validation.email,
+          key_name: result.key_name,
+          config_path: authManager.configPath,
+          credits_remaining: validation.creditsRemaining,
+          plan: validation.planId,
+        });
+        process.stdout.write(line + '\n', () => process.exit(0));
+        return;
+      }
+
+      out('Signed in as ' + validation.email);
+      out('Credits remaining: ' + validation.creditsRemaining);
+      out('Plan: ' + validation.planId);
+      out('API key "' + result.key_name + '" saved to ' + authManager.configPath +
+        (hadConfig ? ' (replaced the previous config)' : ''));
+      out('Next: crawlforge init --client claude-code|claude-desktop|cursor registers the MCP server with a client (this command did not modify any client config).');
+      process.exit(0);
+    });
+}

package/src/cli/index.js

@@ -59,6 +59,7 @@ import { register as registerMonitor } from './commands/monitor.js';
 import { register as registerInstallSkills } from './commands/install-skills.js';
 import { register as registerUninstallSkills } from './commands/uninstall-skills.js';
 import { register as registerInit } from './commands/init.js';
+import { register as registerLogin } from './commands/login.js';
 
 // ─── MCP stdio server mode (backward compatibility) ──────────────────────────
 // Before v4.1.0 the `crawlforge` bin WAS the MCP server. v4.1.0 turned it into
@@ -138,6 +139,7 @@ registerMonitor(program);
 registerInstallSkills(program);
 registerUninstallSkills(program);
 registerInit(program);
+registerLogin(program);
 
 // `crawlforge mcp` / `crawlforge serve` — explicitly start the MCP server over
 // stdio. Extra args (e.g. --http) are read directly by server.js from argv.

package/src/core/AuthManager.js

@@ -241,9 +241,16 @@ class AuthManager {
   }
 
   /**
-   * Check if user has enough credits for a tool
+   * Check if user has enough credits for a tool.
+   *
+   * @param {number} estimatedCredits
+   * @param {object} [ctx] the SDK per-request context, so the low-credit
+   *   warning can ask as a multi-round-trip step (Phase 4.4).
+   * @returns {Promise<boolean|object>} `true`/`false` as before, or an
+   *   `input_required` result the caller must RETURN verbatim — `withAuth`
+   *   detects it, bills nothing and lets the SDK gather the answer.
    */
-  async checkCredits(estimatedCredits = 1) {
+  async checkCredits(estimatedCredits = 1, ctx) {
     // Creator mode has unlimited credits
     if (this.isCreatorMode()) {
       return true;
@@ -277,10 +284,16 @@ class AuthManager {
         this.lastCreditCheck = now;
         this.lastSuccessfulCreditCheck.set(this.config.userId, now);
 
-        // D1.4: If credits are close to running out, elicit confirmation instead of hard-failing
+        // D1.4: If credits are close to running out, elicit confirmation instead
+        // of hard-failing. Phase 4.4: the ask is a round trip now — `ask` hands
+        // an `input_required` result back to withAuth, which returns it unbilled
+        // and is re-entered here with the answer. A client that cannot be asked
+        // still proceeds, which is what the inline helper did.
         if (data.creditsRemaining < estimatedCredits) {
           if (this._elicitation) {
-            const proceed = await this._elicitation.confirm(
+            const gate = this._elicitation.confirm(
+              ctx,
+              'credits:low',
               `Low credits: ${data.creditsRemaining} remaining, this tool needs ~${estimatedCredits}. Proceed anyway?`,
               {
                 credits_remaining: data.creditsRemaining,
@@ -288,8 +301,8 @@ class AuthManager {
                 note: 'Top up at https://www.crawlforge.dev/dashboard',
               }
             );
-            if (!proceed) return false;
-            return true; // user confirmed — let tool attempt it
+            if (gate.status === 'ask') return gate.result;
+            return gate.status === 'proceed'; // confirmed (or unaskable) — let tool attempt it
           }
           return false; // no elicitation — standard hard-fail behavior
         }

package/src/core/ElicitationHelper.js

@@ -1,36 +1,56 @@
 /**
  * ElicitationHelper — MCP Elicitation for CrawlForge
  *
- * Allows tools to request user confirmation or input mid-execution for
- * expensive or ambiguous operations. Falls back gracefully when the
- * MCP client does not support elicitation.
+ * Allows tools to request user confirmation before an expensive or ambiguous
+ * operation. Falls back gracefully when the MCP client cannot be asked.
  *
- * The request goes out as a 2025-era server→client `elicitation/create`,
- * awaited inline in the middle of a tool's work. Two things the SDK does NOT
- * do for us, and which `supported` therefore decides before we send:
+ * Phase 4.4 moved confirmations from an inline server→client request to the
+ * 2026-07-28 MULTI-ROUND-TRIP form: `confirm()` no longer sends anything and no
+ * longer awaits. It returns a verdict, and when the user must be asked the
+ * verdict carries an `input_required` result for the tool to RETURN. The SDK
+ * then either hands it to a 2026-era client or, on a 2025-era connection, runs
+ * its own legacy shim (real `elicitation/create` + handler re-entry). One shape
+ * serves both eras, which is why nothing here branches on the protocol version
+ * any more — the previous era guard reported "unsupported" on 2026-07-28 and
+ * every prompt there was silently skipped.
  *
- *   - `Server.elicitInput()` refuses a client that declared a bare
- *     `elicitation: {}` (it demands `elicitation.form`), even though the SDK's
- *     own capability rule counts a bare declaration as form-capable — that is
- *     the pre-mode 2025 meaning, and it is what the SDK's legacy shim and its
- *     2026 seam both apply. We send through `Server.request()`, which applies
- *     that same lenient rule, so those clients get their prompt.
+ * THE HANDLER IS RE-ENTERED. Everything a tool does above its gate runs a
+ * second time when the answer arrives, so a gate belongs above every fetch and
+ * every side effect. Billing is not a caller's problem: `withAuth` charges an
+ * `input_required` return zero and reports no usage, so a round trip and a
+ * declined confirmation are both free (G4).
  *
- *   - Both `elicitInput()` and `request()` throw on a 2026-07-28-era
- *     connection: that revision has no server→client request channel at all.
- *     There is no inline substitute — the replacement is an `input_required`
- *     result RETURNED by a tools/call handler, which this helper cannot do
- *     from the middle of a tool's execution. So `supported` reports false and
- *     the operation proceeds unasked, exactly as it does for a client with no
- *     elicitation capability. A confirmation prompt is a nicety; failing the
- *     call is not an acceptable substitute. See docs/mcp-spec-adoption.md.
+ * Two properties of the old helper are deliberately preserved:
+ *
+ *   - **Fail-open.** A client that never declared elicitation is not asked, and
+ *     the operation proceeds. This is not politeness — the SDK answers an
+ *     `input_required` return on such a connection with `isError: true`
+ *     ("did not declare the required capability"), so dropping the capability
+ *     gate would turn a nicety into a failed call. Verified against the SDK.
+ *   - **We ask at most once.** `inputResponses` is absent on a first entry and
+ *     present on a retry, so a retry whose answer did not survive the trip
+ *     (a dropped key, an answer of another kind) proceeds rather than asking
+ *     again until the shim's round limit fails the call.
+ *
+ * The one case that cannot be preserved: a client that DECLARES elicitation and
+ * then throws answering it now yields an `isError` result from the SDK where the
+ * old inline path proceeded. The failure happens inside the SDK after the
+ * handler has returned, so nothing here can intercept it. It costs nothing — the
+ * handler did no work, so `withAuth` bills zero.
+ *
+ * Which server instance we ask matters as much as what we ask. server.js
+ * constructs this against the top-level template McpServer, but neither HTTP
+ * leg serves from it — the 2025-era path connects a clone per session and the
+ * modern leg builds one per request, so the template is never `.connect()`ed
+ * and reports no client capabilities. The transport stamps the serving clone on
+ * the request context; this resolves it from there and falls back to the
+ * injected instance, which on stdio IS the connected one. On a 2026-era request
+ * there is no connected instance to read at all — capabilities arrive per
+ * request in the `_meta` envelope, which is why `ctx` is consulted first.
  */
 
-/**
- * First revision of the modern protocol era. Revisions are ISO dates, so
- * lexicographic comparison orders them chronologically (the SDK's own rule).
- */
-const FIRST_MODERN_PROTOCOL_VERSION = '2026-07-28';
+import { inputRequired, inputResponse, CLIENT_CAPABILITIES_META_KEY } from '@modelcontextprotocol/server';
+import { servingRequestId, servingServer } from '../server/requestContext.js';
 
 /** The one-boolean schema a confirmation asks with. */
 const CONFIRM_SCHEMA = {
@@ -70,69 +90,101 @@ export class ElicitationHelper {
   }
 
   /**
-   * Whether an inline elicitation round trip will actually reach the user.
-   * @returns {boolean}
+   * The McpServer this request is served from: the clone the transport stamped
+   * on the request context, else the constructor-injected instance (stdio, and
+   * any caller outside a request context).
+   * @private
+   */
+  get _server() {
+    return servingServer() ?? this._mcpServer;
+  }
+
+  /**
+   * The client's declared capabilities for the request in flight. A 2026-era
+   * request carries them per-request in the `_meta` envelope and has no
+   * connected server instance to read; a 2025-era one has them on the serving
+   * instance and no envelope.
+   * @private
    */
-  get supported() {
-    const server = this._mcpServer?.server;
-    if (typeof server?.request !== 'function') return false;
+  _clientCapabilities(ctx) {
+    const fromEnvelope = ctx?.mcpReq?.envelope?.[CLIENT_CAPABILITIES_META_KEY];
+    if (fromEnvelope) return fromEnvelope;
     try {
-      // No server→client request channel exists on the 2026-07-28 era.
-      const negotiated = server.getNegotiatedProtocolVersion?.();
-      if (typeof negotiated === 'string' && negotiated >= FIRST_MODERN_PROTOCOL_VERSION) return false;
-      return formElicitationDeclared(server.getClientCapabilities?.());
+      return this._server?.server?.getClientCapabilities?.();
     } catch {
-      return false;
+      return undefined;
     }
   }
 
   /**
-   * Send one form-mode `elicitation/create` and return the ElicitResult.
-   * This is byte-for-byte the message `Server.elicitInput()` sends; it just
-   * does not impose that method's stricter `elicitation.form` gate.
-   * @private
+   * Whether asking will actually reach the user rather than fail the call.
+   * @param {object} [ctx] the SDK per-request context the handler received
+   * @returns {boolean}
    */
-  async _elicit(message, requestedSchema) {
-    return this._mcpServer.server.request({
-      method: 'elicitation/create',
-      params: { message, requestedSchema, mode: 'form' },
-    });
+  supported(ctx) {
+    return formElicitationDeclared(this._clientCapabilities(ctx));
   }
 
   /**
    * Ask for user confirmation before proceeding with an expensive operation.
-   * Returns true if confirmed (or if elicitation is unsupported — fail-open
-   * so tools continue working in non-elicitation clients).
+   * SYNCHRONOUS — it performs no I/O. Do not `await` it.
    *
-   * @param {string} message - Human-readable explanation of what requires confirmation
-   * @param {object} [details] - Additional context (projected cost, URL count, etc.)
-   * @returns {Promise<boolean>} - true = proceed, false = cancel
+   * @param {object|undefined} ctx - the SDK per-request context the handler received
+   * @param {string} key - stable identifier for this question, unique across tools
+   * @param {string} message - human-readable explanation of what requires confirmation
+   * @param {object} [details] - additional context (projected cost, URL count, etc.)
+   * @returns {{status:'proceed'}|{status:'cancelled'}|{status:'ask', result: object}}
+   *   `ask` carries an `input_required` result the caller must RETURN verbatim.
    */
-  async confirm(message, details = {}) {
-    if (!this.supported) {
-      this._logger.warn('Elicitation not supported by client — proceeding without confirmation', { message });
-      return true;
-    }
+  confirm(ctx, key, message, details = {}) {
+    const responses = ctx?.mcpReq?.inputResponses;
+    const answered = inputResponse(responses, key);
 
-    try {
-      const detailLines = Object.entries(details)
-        .map(([k, v]) => `  ${k}: ${v}`)
-        .join('\n');
-      const fullMessage = detailLines ? `${message}\n\n${detailLines}` : message;
+    if (answered.kind === 'elicit') {
+      // Only an explicit accept + confirmed=true proceeds; decline/cancel = stop.
+      return answered.action === 'accept' && answered.content?.confirmed === true
+        ? { status: 'proceed' }
+        : { status: 'cancelled' };
+    }
 
-      const result = await this._elicit(fullMessage, CONFIRM_SCHEMA);
+    // A retry carries an `inputResponses` object even when this key's answer
+    // did not survive it. Asking again would burn the shim's rounds and end in
+    // a failed call, so one unanswered round trip proceeds instead.
+    if (responses !== undefined) {
+      this._logger.warn('Elicitation answer did not come back — proceeding without confirmation', { key });
+      return { status: 'proceed' };
+    }
 
-      // Only an explicit accept + confirmed=true proceeds; decline/cancel = stop.
-      return result?.action === 'accept' && result?.content?.confirmed === true;
-    } catch (err) {
-      this._logger.warn('Elicitation request failed — proceeding without confirmation', { error: err.message });
-      return true; // fail-open
+    if (!this.supported(ctx)) {
+      this._logger.warn('Elicitation not supported by client — proceeding without confirmation', { message });
+      return { status: 'proceed' };
     }
+
+    const detailLines = Object.entries(details)
+      .map(([k, v]) => `  ${k}: ${v}`)
+      .join('\n');
+    const fullMessage = detailLines ? `${message}\n\n${detailLines}` : message;
+
+    return {
+      status: 'ask',
+      result: inputRequired({
+        inputRequests: {
+          [key]: inputRequired.elicit({ message: fullMessage, requestedSchema: CONFIRM_SCHEMA }),
+        },
+      }),
+    };
   }
 
   /**
    * Ask the user to provide a string value (e.g. missing schema field).
    *
+   * Still the 2025-era inline form, and still reached by no tool — this is the
+   * repo's one caller-less elicitation path, left as-is under G6 (dead code is
+   * reported, not deleted). It therefore keeps the era guard that `confirm()`
+   * shed: an inline request throws on a 2026-era connection, so the default is
+   * returned there rather than the call being failed. Converting it to a round
+   * trip is speculative until something calls it.
+   *
    * @param {string} message
    * @param {object} [options]
    * @param {string} [options.fieldName]
@@ -141,24 +193,43 @@ export class ElicitationHelper {
    * @returns {Promise<string|null>} - The user-provided value or null if cancelled/unsupported
    */
   async requestString(message, { fieldName = 'value', fieldDescription = '', defaultValue } = {}) {
-    if (!this.supported) {
+    const server = this._server?.server;
+    const inlineUsable = typeof server?.request === 'function'
+      && !this._modernEra(server)
+      && formElicitationDeclared(this._clientCapabilities());
+
+    if (!inlineUsable) {
       this._logger.warn('Elicitation not supported — using default value', { fieldName, defaultValue });
       return defaultValue || null;
     }
 
     try {
-      const result = await this._elicit(message, {
-        type: 'object',
-        properties: {
-          [fieldName]: {
-            type: 'string',
-            title: fieldName,
-            description: fieldDescription,
-            ...(defaultValue ? { default: defaultValue } : {}),
+      // relatedRequestId ties the prompt to the tools/call in flight. Without it
+      // the 2025-era HTTP transport puts the request on the standalone GET SSE
+      // stream and drops it outright when the client never opened one.
+      const relatedRequestId = servingRequestId();
+      const result = await server.request(
+        {
+          method: 'elicitation/create',
+          params: {
+            message,
+            requestedSchema: {
+              type: 'object',
+              properties: {
+                [fieldName]: {
+                  type: 'string',
+                  title: fieldName,
+                  description: fieldDescription,
+                  ...(defaultValue ? { default: defaultValue } : {}),
+                },
+              },
+              required: [fieldName],
+            },
+            mode: 'form',
           },
         },
-        required: [fieldName],
-      });
+        relatedRequestId === null ? undefined : { relatedRequestId }
+      );
 
       // The answer is client-supplied and no longer schema-checked by the SDK
       // on this path, so hold it to the type we asked for.
@@ -171,4 +242,14 @@ export class ElicitationHelper {
       return defaultValue || null;
     }
   }
+
+  /** @private The 2026-07-28 era has no server→client request channel. */
+  _modernEra(server) {
+    try {
+      const negotiated = server?.getNegotiatedProtocolVersion?.();
+      return typeof negotiated === 'string' && negotiated >= '2026-07-28';
+    } catch {
+      return false;
+    }
+  }
 }

package/src/server/requestContext.js

@@ -69,3 +69,53 @@ export function setActualCost(n) {
 export function reportedActualCost() {
   return requestContext.getStore()?.actualCost ?? null;
 }
+
+/**
+ * Record the McpServer instance that is actually serving this request, and the
+ * wire era it speaks.
+ *
+ * Neither HTTP leg serves from the top-level McpServer that server.js
+ * registers everything on: the 2025-era path connects one clone per session,
+ * and the modern leg builds a fresh clone per request (see
+ * transports/streamableHttp.js). Only a clone is ever `.connect()`ed, so only a
+ * clone has a negotiated protocol version, the client's declared capabilities,
+ * and a channel to send a server-to-client request on. The template has none of
+ * those, which is why anything reading them off it (ElicitationHelper) got
+ * `undefined` on every HTTP request.
+ *
+ * Stdio stamps nothing: there the top-level instance IS the connected one, and
+ * the accessors below return null so callers fall back to it.
+ *
+ * @param {object|null} server the serving McpServer
+ * @param {'legacy'|'modern'|null} [era] the wire era it serves
+ */
+export function setServingServer(server, era = null) {
+  const store = requestContext.getStore();
+  if (!store) return;
+  store.servingServer = server ?? null;
+  store.servingEra = era;
+}
+
+/** The McpServer serving this request, or null on stdio / outside a context. */
+export function servingServer() {
+  return requestContext.getStore()?.servingServer ?? null;
+}
+
+/** The wire era serving this request: 'legacy' | 'modern' | null (stdio). */
+export function servingEra() {
+  return requestContext.getStore()?.servingEra ?? null;
+}
+
+/**
+ * The JSON-RPC id of the request being served, or null when unknown.
+ *
+ * A server-to-client request sent from inside a tool has to say which inbound
+ * request it belongs to: the 2025-era streamable HTTP transport routes an
+ * unrelated request to the standalone GET SSE stream and silently DROPS it when
+ * the client never opened one, which turns an elicitation prompt into a
+ * 60-second stall before it fails open. withAuth stamps this from the SDK's
+ * per-request `ctx`; stdio has no streams to pick between and ignores it.
+ */
+export function servingRequestId() {
+  return requestContext.getStore()?.servingRequestId ?? null;
+}

package/src/server/transports/streamableHttp.js

@@ -31,7 +31,7 @@ import { NodeStreamableHTTPServerTransport, toNodeHandler, toWebRequest } from "
 import { createServer } from 'node:http';
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { requestContext } from '../requestContext.js';
+import { requestContext, setServingServer } from '../requestContext.js';
 import { applySpecHygiene } from '../specHygiene.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
@@ -214,7 +214,14 @@ export async function connectStreamableHttp(server, authManager, logger, options
   // this handler, so the modern leg never has to serve one. The SDK owns the
   // Content-Type gate (415), the Mcp-Method/Mcp-Name cross-checks (-32020 on
   // 400) and `server/discover`; nothing here re-implements them.
-  const modernHandler = createMcpHandler(() => cloneServerForSession(server), {
+  // The factory runs once per request, inside the requestContext.run() below,
+  // so the clone it builds can be stamped on the store: that clone — never the
+  // template — is the instance this request is actually served from.
+  const modernHandler = createMcpHandler((ctx) => {
+    const requestServer = cloneServerForSession(server);
+    setServingServer(requestServer, ctx?.era ?? 'modern');
+    return requestServer;
+  }, {
     legacy: 'reject',
     onerror: (err) => logger.warn('2026-era MCP request rejected', { error: err?.message })
   });
@@ -362,7 +369,10 @@ export async function connectStreamableHttp(server, authManager, logger, options
       const existing = sessionIdHeader ? sessions.get(String(sessionIdHeader)) : undefined;
 
       if (existing) {
-        await requestContext.run({ internal }, () => existing.transport.handleRequest(req, res, parsedBody));
+        await requestContext.run(
+          { internal, servingServer: existing.server, servingEra: 'legacy' },
+          () => existing.transport.handleRequest(req, res, parsedBody)
+        );
         return;
       }
 
@@ -395,7 +405,10 @@ export async function connectStreamableHttp(server, authManager, logger, options
 
       try {
         await sessionServer.connect(transport);
-        await requestContext.run({ internal }, () => transport.handleRequest(req, res, parsedBody));
+        await requestContext.run(
+          { internal, servingServer: sessionServer, servingEra: 'legacy' },
+          () => transport.handleRequest(req, res, parsedBody)
+        );
       } catch (err) {
         logger.error('Streamable HTTP session initialization failed', { error: err?.message });
         safeClose(transport);

package/src/server/withAuth.js

@@ -8,7 +8,11 @@
  *     so a valid API key is required for every invocation
  *   - try/finally guarantees a single `tool invocation` log line per call
  *   - log payload: { toolName, paramHash, durationMs, outcome, creditCost, creatorMode }
- *   - outcome ∈ { 'success' | 'error' | 'insufficient_credits' }
+ *   - outcome ∈ { 'success' | 'error' | 'insufficient_credits' | 'input_required' }
+ *   - an `input_required` return (Phase 4.4) is a round trip, not an answer: the
+ *     handler did no work, so it is billed NOTHING and reports no usage. The
+ *     SDK re-enters the handler with the reply and the terminal entry bills
+ *     once, so a confirmation costs exactly what the call always cost (G4).
  *   - error results get a "Next step:" hint naming the tool to try next
  *     (src/server/fallbackHints.js) so a failure is not followed by a blind retry
  *   - emits an OTel span via src/observability/tracing.js (no-op if disabled)
@@ -16,6 +20,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { isInputRequiredResult } from '@modelcontextprotocol/server';
 import { recordToolInvocation } from '../observability/tracing.js';
 import { isInternalRequest, preflightRefusal, reportedActualCost, requestContext } from './requestContext.js';
 import { appendFallbackHint } from './fallbackHints.js';
@@ -71,7 +76,7 @@ export function hashParams(params) {
  */
 export function makeWithAuth({ authManager, logger, metrics = null, mcpServer = null }) {
   return function withAuth(toolName, handler) {
-    const invoke = async (params) => {
+    const invoke = async (params, ctx) => {
       const startTime = Date.now();
       const paramHash = hashParams(params);
       const creatorMode = authManager.isCreatorMode();
@@ -109,7 +114,14 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
         // end user's credits before forwarding — checking the static key's
         // balance here would gate users on an unrelated account).
         if (!billingExempt) {
-          const hasCredits = await authManager.checkCredits(creditCost);
+          const hasCredits = await authManager.checkCredits(creditCost, ctx);
+          // The low-credit warning asks as a round trip (Phase 4.4). Nothing has
+          // run, so this costs nothing and reports no usage; the SDK re-enters
+          // with the answer.
+          if (isInputRequiredResult(hasCredits)) {
+            outcome = 'input_required';
+            return hasCredits;
+          }
           if (!hasCredits) {
             outcome = 'insufficient_credits';
             return {
@@ -127,7 +139,21 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
         }
 
         handlerStarted = true;
-        const result = await handler(params);
+        const result = await handler(params, ctx);
+
+        // Phase 4.4: a multi-round-trip handler answers `input_required` when it
+        // needs the user before it can start. Nothing was fetched, so nothing is
+        // owed: no charge, no usage report, and none of the result stages below
+        // (there is no result yet to redact, shape or price). The SDK gathers the
+        // answer and re-enters this same wrapper; whichever entry finally returns
+        // a real result is the one that bills, exactly once. Without this branch
+        // an `input_required` is not `isError`, so it books as a success and
+        // bills in full on every round — up to eight — for a call that did no
+        // work, and a declined confirmation bills too (G4).
+        if (isInputRequiredResult(result)) {
+          outcome = 'input_required';
+          return result;
+        }
 
         // Tools catch their own failures and return { isError:true } rather than
         // throwing (the shared pattern in server.js). That is still an ERROR
@@ -275,11 +301,23 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
 
     // Every invocation runs in its own context so the compliance gate can stamp
     // a refusal where the billing decision can see it. Any outer store (the
-    // HTTP transport's `internal` flag) is spread in, not replaced — and stdio
-    // callers, who have no transport-provided store, get one here.
-    return async (params) => requestContext.run(
-      { ...(requestContext.getStore() ?? {}), preflightRefusal: null, actualCost: null },
-      () => invoke(params)
+    // HTTP transport's `internal` flag, the serving McpServer) is spread in,
+    // not replaced — and stdio callers, who have no transport-provided store,
+    // get one here.
+    //
+    // `ctx` is the SDK's per-request context (v2 calls a tool callback with
+    // `(args, ctx)`). It is passed straight through to the handler; existing
+    // 1-arity handlers ignore it. Its request id is stamped on the context so a
+    // server-to-client request sent from inside the tool can ride the same
+    // stream as this call — see servingRequestId() in requestContext.js.
+    return async (params, ctx) => requestContext.run(
+      {
+        ...(requestContext.getStore() ?? {}),
+        preflightRefusal: null,
+        actualCost: null,
+        servingRequestId: ctx?.mcpReq?.id
+      },
+      () => invoke(params, ctx)
     );
   };
 }

package/src/tools/advanced/batchScrape/index.js

@@ -83,41 +83,51 @@ export class BatchScrapeTool extends EventEmitter {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     try {
       const validated = BatchScrapeSchema.parse(params);
-      this.stats.totalBatches++;
       const batchId = this._generateBatchId();
-      const startTime = Date.now();
-
-      this._log('info', `Starting batch scrape ${batchId} with ${validated.urls.length} URLs in ${validated.mode} mode`);
-
-      const urlConfigs = this._normalizeUrlConfigs(validated.urls, validated);
 
-      let webhookConfig = null;
-      if (validated.webhook && this.enableWebhookNotifications) {
-        webhookConfig = this._registerWebhook(validated.webhook, batchId);
-      }
-
-      // D1.4: Elicitation — warn when batch is large in sync mode
-      if (validated.mode === 'sync' && urlConfigs.length > 25) {
-        const proceed = await this._elicitation.confirm(
-          `batch_scrape (sync mode) will fetch ${urlConfigs.length} URLs synchronously. This may take a while and consume significant credits.`,
+      // D1.4: Elicitation — warn when batch is large in sync mode. An
+      // unanswered gate returns an input-required result the SDK answers by
+      // re-entering this handler from the top, so it runs before anything that
+      // leaves a trace: below it are the batch counter and the webhook
+      // registration, which a second entry would repeat (a second webhook
+      // registration for one batch). The count comes from validated.urls,
+      // which _normalizeUrlConfigs maps one-for-one.
+      if (validated.mode === 'sync' && validated.urls.length > 25) {
+        const gate = this._elicitation.confirm(
+          ctx,
+          'batch_scrape:large_sync',
+          `batch_scrape (sync mode) will fetch ${validated.urls.length} URLs synchronously. This may take a while and consume significant credits.`,
           {
-            url_count: urlConfigs.length,
+            url_count: validated.urls.length,
             mode: 'sync',
             suggestion: 'Consider using mode:"async" for large batches.',
           }
         );
-        if (!proceed) {
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
           return {
             batchId, mode: 'sync', success: false,
             error: 'Batch scrape cancelled by user (elicitation declined).',
-            totalUrls: urlConfigs.length,
+            totalUrls: validated.urls.length,
           };
         }
       }
 
+      this.stats.totalBatches++;
+      const startTime = Date.now();
+
+      this._log('info', `Starting batch scrape ${batchId} with ${validated.urls.length} URLs in ${validated.mode} mode`);
+
+      const urlConfigs = this._normalizeUrlConfigs(validated.urls, validated);
+
+      let webhookConfig = null;
+      if (validated.webhook && this.enableWebhookNotifications) {
+        webhookConfig = this._registerWebhook(validated.webhook, batchId);
+      }
+
       if (validated.mode === 'sync') {
         return await this._processBatchSync(batchId, urlConfigs, validated, webhookConfig, startTime);
       } else {

package/src/tools/agent/agent.js

@@ -35,16 +35,21 @@ export class AgentTool {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     const validated = AgentInputSchema.parse(params);
 
-    // Request confirmation before a pro run (expensive)
+    // Request confirmation before a pro run (expensive). An unanswered gate
+    // returns an input-required result the SDK answers by re-entering this
+    // handler from the top, so nothing above it may fetch or leave a trace.
     if (validated.model === 'pro') {
-      const proceed = await this._elicitation.confirm(
+      const gate = this._elicitation.confirm(
+        ctx,
+        'agent:pro_model',
         'agent tool: pro model uses ResearchOrchestrator and may incur significant costs.',
         { model: 'pro', maxUrls: validated.maxUrls, note: 'External LLM API costs billed separately if keys are set.' }
       );
-      if (!proceed) {
+      if (gate.status === 'ask') return gate.result;
+      if (gate.status === 'cancelled') {
         return {
           success: false,
           cancelled: true,

package/src/tools/crawl/crawlDeep.js

@@ -117,7 +117,7 @@ export class CrawlDeepTool {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     try {
       const validated = CrawlDeepSchema.parse(params);
 
@@ -147,9 +147,14 @@ export class CrawlDeepTool {
         if (cached) return { ...cached, cached: true };
       }
 
-      // D1.4: Elicitation — warn when max_pages is very high
+      // D1.4: Elicitation — warn when max_pages is very high. An unanswered
+      // gate returns an input-required result the SDK answers by re-entering
+      // this handler from the top; everything above is the clamp arithmetic and
+      // a cache read, so a second entry fetches nothing and leaves no trace.
       if (effectiveMaxPages > 500) {
-        const proceed = await this._elicitation.confirm(
+        const gate = this._elicitation.confirm(
+          ctx,
+          'crawl_deep:max_pages',
           `crawl_deep will crawl up to ${effectiveMaxPages} pages from ${validated.url}. Large crawls consume many credits.`,
           {
             url: validated.url,
@@ -157,7 +162,8 @@ export class CrawlDeepTool {
             max_depth: effectiveMaxDepth,
           }
         );
-        if (!proceed) {
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
           return {
             success: false,
             error: 'Crawl cancelled by user (elicitation declined).',

package/src/tools/extract/extractStructured.js

@@ -174,36 +174,78 @@ export class ExtractStructuredTool {
    * @param {Object} params - Extraction parameters
    * @returns {Promise<Object>} Extraction result
    */
-  async execute(params) {
+  async execute(params, ctx) {
     const startTime = Date.now();
 
     try {
       const validated = ExtractStructuredSchema.parse(params);
       const { url, schema, prompt, llmConfig, fallbackToSelectors, selectorHints, respect_robots, user_agent, verify_numbers } = validated;
 
-      // Step 1: Fetch and parse — shared helper strips scripts/styles/iframes/svgs
-      const { html, $, textContent, warnings } = await fetchAndParse(url, {
-        userAgent: user_agent || this.userAgent,
-        respectRobots: respect_robots,
-        tool: 'extract_structured'
-      });
-
-      // What the model reads — see shownText().
-      const shown = shownText($, html, url, textContent);
-
-      // Step 3: Try LLM extraction first
       let extractionResult = null;
       let extractionMethod = 'llm';
       let llmErrorMessage = null;
       let llmAvailable = false;
+      let llm = null;
 
+      // Step 0: LLM readiness, resolved before the fetch so the D1.4 gate below
+      // can ask before any network work — an unanswered gate returns an
+      // input-required result the SDK answers by re-entering this handler from
+      // the top, and everything above the gate runs a second time.
       try {
-        const llm = this._ensureLLMManager(llmConfig || {});
+        llm = this._ensureLLMManager(llmConfig || {});
         // ready() probes Ollama, which has no API key to gate on. isAvailable()
         // alone reported false on any machine without a cloud key, so a running
         // local Ollama was never used.
         llmAvailable = await llm.ready();
-        if (llmAvailable) {
+      } catch (llmError) {
+        // No usable LLM — this falls through to the CSS fallback. Keep the
+        // message so callers can tell "LLM broken" apart from "no LLM
+        // configured".
+        llmErrorMessage = llmError.message;
+      }
+
+      // D1.4: no LLM configured and the schema demands more than 3 required
+      // fields — confirm before running the lower-fidelity CSS fallback. With
+      // no LLM, step 3 extracts nothing, so landing on that fallback is already
+      // settled here, before the page is fetched.
+      const requiredCount = (schema.required || []).length;
+      if (fallbackToSelectors !== false && !llmAvailable && requiredCount > 3) {
+        const gate = this._elicitation.confirm(
+          ctx,
+          'extract_structured:no_llm_required_fields',
+          `No LLM provider is configured and the requested schema has ${requiredCount} required fields. ` +
+          `extract_structured will fall back to lower-fidelity CSS selector extraction, which may miss required fields.`,
+          { url, required_fields: requiredCount }
+        );
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
+          return {
+            success: false,
+            url,
+            data: {},
+            extraction_method: 'none',
+            confidence: 0,
+            schema_used: schema,
+            processingTime: Date.now() - startTime,
+            error: 'Extraction cancelled by user (elicitation declined).',
+            validation: { valid: false, errors: ['Extraction cancelled by user (elicitation declined).'] }
+          };
+        }
+      }
+
+      // Step 1: Fetch and parse — shared helper strips scripts/styles/iframes/svgs
+      const { html, $, textContent, warnings } = await fetchAndParse(url, {
+        userAgent: user_agent || this.userAgent,
+        respectRobots: respect_robots,
+        tool: 'extract_structured'
+      });
+
+      // What the model reads — see shownText().
+      const shown = shownText($, html, url, textContent);
+
+      // Step 3: Try LLM extraction first (readiness resolved in step 0)
+      if (llmAvailable) {
+        try {
           const result = await llm.extractStructured(shown, schema, {
             prompt: prompt || '',
             maxContentLength: SHOWN_TEXT_BUDGET
@@ -218,12 +260,11 @@ export class ExtractStructuredTool {
           } else {
             llmErrorMessage = result?.error || 'LLM did not return usable JSON';
           }
+        } catch (llmError) {
+          // LLM failed — will fall through to CSS fallback.
+          extractionResult = null;
+          llmErrorMessage = llmError.message;
         }
-      } catch (llmError) {
-        // LLM failed — will fall through to CSS fallback. Keep the message so
-        // callers can tell "LLM broken" apart from "no LLM configured".
-        extractionResult = null;
-        llmErrorMessage = llmError.message;
       }
 
       // Step 3b (3.4): numeric provenance. Only the LLM path invents numbers —
@@ -318,31 +359,9 @@ export class ExtractStructuredTool {
         if (guarded.checked.skipped) provenance.skipped = guarded.checked.skipped;
       }
 
-      // Step 4: CSS selector fallback if LLM unavailable or failed
+      // Step 4: CSS selector fallback if LLM unavailable or failed (the D1.4
+      // confirmation for this path is gated above, before the fetch)
       if (!extractionResult && fallbackToSelectors !== false) {
-        // D1.4: no LLM configured and the schema demands more than 3 required
-        // fields — confirm before running the lower-fidelity CSS fallback.
-        const requiredCount = (schema.required || []).length;
-        if (!llmAvailable && requiredCount > 3) {
-          const proceed = await this._elicitation.confirm(
-            `No LLM provider is configured and the requested schema has ${requiredCount} required fields. ` +
-            `extract_structured will fall back to lower-fidelity CSS selector extraction, which may miss required fields.`,
-            { url, required_fields: requiredCount }
-          );
-          if (!proceed) {
-            return {
-              success: false,
-              url,
-              data: {},
-              extraction_method: 'none',
-              confidence: 0,
-              schema_used: schema,
-              processingTime: Date.now() - startTime,
-              error: 'Extraction cancelled by user (elicitation declined).',
-              validation: { valid: false, errors: ['Extraction cancelled by user (elicitation declined).'] }
-            };
-          }
-        }
         extractionResult = this._cssExtraction($, schema, selectorHints || {});
         extractionMethod = 'css_fallback';
       }

package/src/tools/research/deepResearch.js

@@ -115,7 +115,7 @@ export class DeepResearchTool {
     this._elicitation = new ElicitationHelper({ mcpServer });
   }
 
-  async execute(params) {
+  async execute(params, ctx) {
     try {
       const validated = DeepResearchSchema.parse(params);
       const sessionId = this.generateSessionId();
@@ -137,10 +137,15 @@ export class DeepResearchTool {
       }
 
       // D1.4: Elicitation — warn user if projected cost exceeds 50 credits
-      // deep_research costs approximately 1 credit per URL; maxUrls > 50 → confirm
+      // deep_research costs approximately 1 credit per URL; maxUrls > 50 → confirm.
+      // An unanswered gate returns an input-required result the SDK answers by
+      // re-entering this handler from the top, so it sits above the session
+      // registration below — a second entry would otherwise leak a session.
       if (validated.maxUrls > 50) {
         const projectedCredits = validated.maxUrls;
-        const proceed = await this._elicitation.confirm(
+        const gate = this._elicitation.confirm(
+          ctx,
+          'deep_research:max_urls',
           `deep_research will scan up to ${validated.maxUrls} URLs, projecting ~${projectedCredits} credits.`,
           {
             topic: validated.topic,
@@ -148,7 +153,8 @@ export class DeepResearchTool {
             max_urls: validated.maxUrls,
           }
         );
-        if (!proceed) {
+        if (gate.status === 'ask') return gate.result;
+        if (gate.status === 'cancelled') {
           return {
             success: false,
             error: 'Research cancelled by user before starting (elicitation declined).',