@xortex/xcode 3.0.0

package/tools/ToolSearchTool/prompt.ts

@@ -0,0 +1,121 @@
+import { feature } from 'bun:bundle'
+import { isReplBridgeActive } from '../../bootstrap/state.js'
+import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
+import type { Tool } from '../../Tool.js'
+import { AGENT_TOOL_NAME } from '../AgentTool/constants.js'
+
+// Dead code elimination: Brief tool name only needed when KAIROS or KAIROS_BRIEF is on
+/* eslint-disable @typescript-eslint/no-require-imports */
+const BRIEF_TOOL_NAME: string | null =
+  feature('KAIROS') || feature('KAIROS_BRIEF')
+    ? (
+        require('../BriefTool/prompt.js') as typeof import('../BriefTool/prompt.js')
+      ).BRIEF_TOOL_NAME
+    : null
+const SEND_USER_FILE_TOOL_NAME: string | null = feature('KAIROS')
+  ? (
+      require('../SendUserFileTool/prompt.js') as typeof import('../SendUserFileTool/prompt.js')
+    ).SEND_USER_FILE_TOOL_NAME
+  : null
+
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+export { TOOL_SEARCH_TOOL_NAME } from './constants.js'
+
+import { TOOL_SEARCH_TOOL_NAME } from './constants.js'
+
+const PROMPT_HEAD = `Fetches full schema definitions for deferred tools so they can be called.
+
+`
+
+// Matches isDeferredToolsDeltaEnabled in toolSearch.ts (not imported —
+// toolSearch.ts imports from this file). When enabled: tools announced
+// via system-reminder attachments. When disabled: prepended
+// <available-deferred-tools> block (pre-gate behavior).
+function getToolLocationHint(): string {
+  const deltaEnabled =
+    process.env.USER_TYPE === 'ant' ||
+    getFeatureValue_CACHED_MAY_BE_STALE('tengu_glacier_2xr', false)
+  return deltaEnabled
+    ? 'Deferred tools appear by name in <system-reminder> messages.'
+    : 'Deferred tools appear by name in <available-deferred-tools> messages.'
+}
+
+const PROMPT_TAIL = ` Until fetched, only the name is known — there is no parameter schema, so the tool cannot be invoked. This tool takes a query, matches it against the deferred tool list, and returns the matched tools' complete JSONSchema definitions inside a <functions> block. Once a tool's schema appears in that result, it is callable exactly like any tool defined at the top of the prompt.
+
+Result format: each matched tool appears as one <function>{"description": "...", "name": "...", "parameters": {...}}</function> line inside the <functions> block — the same encoding as the tool list at the top of this prompt.
+
+Query forms:
+- "select:Read,Edit,Grep" — fetch these exact tools by name
+- "notebook jupyter" — keyword search, up to max_results best matches
+- "+slack send" — require "slack" in the name, rank by remaining terms`
+
+/**
+ * Check if a tool should be deferred (requires ToolSearch to load).
+ * A tool is deferred if:
+ * - It's an MCP tool (always deferred - workflow-specific)
+ * - It has shouldDefer: true
+ *
+ * A tool is NEVER deferred if it has alwaysLoad: true (MCP tools set this via
+ * _meta['anthropic/alwaysLoad']). This check runs first, before any other rule.
+ */
+export function isDeferredTool(tool: Tool): boolean {
+  // Explicit opt-out via _meta['anthropic/alwaysLoad'] — tool appears in the
+  // initial prompt with full schema. Checked first so MCP tools can opt out.
+  if (tool.alwaysLoad === true) return false
+
+  // MCP tools are always deferred (workflow-specific)
+  if (tool.isMcp === true) return true
+
+  // Never defer ToolSearch itself — the model needs it to load everything else
+  if (tool.name === TOOL_SEARCH_TOOL_NAME) return false
+
+  // Fork-first experiment: Agent must be available turn 1, not behind ToolSearch.
+  // Lazy require: static import of forkSubagent → coordinatorMode creates a cycle
+  // through constants/tools.ts at module init.
+  if (feature('FORK_SUBAGENT') && tool.name === AGENT_TOOL_NAME) {
+    type ForkMod = typeof import('../AgentTool/forkSubagent.js')
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const m = require('../AgentTool/forkSubagent.js') as ForkMod
+    if (m.isForkSubagentEnabled()) return false
+  }
+
+  // Brief is the primary communication channel whenever the tool is present.
+  // Its prompt contains the text-visibility contract, which the model must
+  // see without a ToolSearch round-trip. No runtime gate needed here: this
+  // tool's isEnabled() IS isBriefEnabled(), so being asked about its deferral
+  // status implies the gate already passed.
+  if (
+    (feature('KAIROS') || feature('KAIROS_BRIEF')) &&
+    BRIEF_TOOL_NAME &&
+    tool.name === BRIEF_TOOL_NAME
+  ) {
+    return false
+  }
+
+  // SendUserFile is a file-delivery communication channel (sibling of Brief).
+  // Must be immediately available without a ToolSearch round-trip.
+  if (
+    feature('KAIROS') &&
+    SEND_USER_FILE_TOOL_NAME &&
+    tool.name === SEND_USER_FILE_TOOL_NAME &&
+    isReplBridgeActive()
+  ) {
+    return false
+  }
+
+  return tool.shouldDefer === true
+}
+
+/**
+ * Format one deferred-tool line for the <available-deferred-tools> user
+ * message. Search hints (tool.searchHint) are not rendered — the
+ * hints A/B (exp_xenhnnmn0smrx4, stopped Mar 21) showed no benefit.
+ */
+export function formatDeferredToolLine(tool: Tool): string {
+  return tool.name
+}
+
+export function getPrompt(): string {
+  return PROMPT_HEAD + getToolLocationHint() + PROMPT_TAIL
+}

package/tools/TungstenTool/TungstenTool.ts

@@ -0,0 +1,4 @@
+export const TungstenTool = { name: 'TungstenTool' } as any;
+export function clearSessionsWithTungstenUsage() {}
+export function resetInitializationState() {}
+export const TungstenLiveMonitor = () => null;

package/tools/WebFetchTool/UI.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+import { MessageResponse } from '../../components/MessageResponse.js';
+import { TOOL_SUMMARY_MAX_LENGTH } from '../../constants/toolLimits.js';
+import { Box, Text } from '../../ink.js';
+import type { ToolProgressData } from '../../Tool.js';
+import type { ProgressMessage } from '../../types/message.js';
+import { formatFileSize, truncate } from '../../utils/format.js';
+import type { Output } from './WebFetchTool.js';
+export function renderToolUseMessage({
+  url,
+  prompt
+}: Partial<{
+  url: string;
+  prompt: string;
+}>, {
+  verbose
+}: {
+  theme?: string;
+  verbose: boolean;
+}): React.ReactNode {
+  if (!url) {
+    return null;
+  }
+  if (verbose) {
+    return `url: "${url}"${verbose && prompt ? `, prompt: "${prompt}"` : ''}`;
+  }
+  return url;
+}
+export function renderToolUseProgressMessage(): React.ReactNode {
+  return <MessageResponse height={1}>
+      <Text dimColor>Fetching…</Text>
+    </MessageResponse>;
+}
+export function renderToolResultMessage({
+  bytes,
+  code,
+  codeText,
+  result
+}: Output, _progressMessagesForMessage: ProgressMessage<ToolProgressData>[], {
+  verbose
+}: {
+  verbose: boolean;
+}): React.ReactNode {
+  const formattedSize = formatFileSize(bytes);
+  if (verbose) {
+    return <Box flexDirection="column">
+        <MessageResponse height={1}>
+          <Text>
+            Received <Text bold>{formattedSize}</Text> ({code} {codeText})
+          </Text>
+        </MessageResponse>
+        <Box flexDirection="column">
+          <Text>{result}</Text>
+        </Box>
+      </Box>;
+  }
+  return <MessageResponse height={1}>
+      <Text>
+        Received <Text bold>{formattedSize}</Text> ({code} {codeText})
+      </Text>
+    </MessageResponse>;
+}
+export function getToolUseSummary(input: Partial<{
+  url: string;
+  prompt: string;
+}> | undefined): string | null {
+  if (!input?.url) {
+    return null;
+  }
+  return truncate(input.url, TOOL_SUMMARY_MAX_LENGTH);
+}
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJuYW1lcyI6WyJSZWFjdCIsIk1lc3NhZ2VSZXNwb25zZSIsIlRPT0xfU1VNTUFSWV9NQVhfTEVOR1RIIiwiQm94IiwiVGV4dCIsIlRvb2xQcm9ncmVzc0RhdGEiLCJQcm9ncmVzc01lc3NhZ2UiLCJmb3JtYXRGaWxlU2l6ZSIsInRydW5jYXRlIiwiT3V0cHV0IiwicmVuZGVyVG9vbFVzZU1lc3NhZ2UiLCJ1cmwiLCJwcm9tcHQiLCJQYXJ0aWFsIiwidmVyYm9zZSIsInRoZW1lIiwiUmVhY3ROb2RlIiwicmVuZGVyVG9vbFVzZVByb2dyZXNzTWVzc2FnZSIsInJlbmRlclRvb2xSZXN1bHRNZXNzYWdlIiwiYnl0ZXMiLCJjb2RlIiwiY29kZVRleHQiLCJyZXN1bHQiLCJfcHJvZ3Jlc3NNZXNzYWdlc0Zvck1lc3NhZ2UiLCJmb3JtYXR0ZWRTaXplIiwiZ2V0VG9vbFVzZVN1bW1hcnkiLCJpbnB1dCJdLCJzb3VyY2VzIjpbIlVJLnRzeCJdLCJzb3VyY2VzQ29udGVudCI6WyJpbXBvcnQgUmVhY3QgZnJvbSAncmVhY3QnXG5pbXBvcnQgeyBNZXNzYWdlUmVzcG9uc2UgfSBmcm9tICcuLi8uLi9jb21wb25lbnRzL01lc3NhZ2VSZXNwb25zZS5qcydcbmltcG9ydCB7IFRPT0xfU1VNTUFSWV9NQVhfTEVOR1RIIH0gZnJvbSAnLi4vLi4vY29uc3RhbnRzL3Rvb2xMaW1pdHMuanMnXG5pbXBvcnQgeyBCb3gsIFRleHQgfSBmcm9tICcuLi8uLi9pbmsuanMnXG5pbXBvcnQgdHlwZSB7IFRvb2xQcm9ncmVzc0RhdGEgfSBmcm9tICcuLi8uLi9Ub29sLmpzJ1xuaW1wb3J0IHR5cGUgeyBQcm9ncmVzc01lc3NhZ2UgfSBmcm9tICcuLi8uLi90eXBlcy9tZXNzYWdlLmpzJ1xuaW1wb3J0IHsgZm9ybWF0RmlsZVNpemUsIHRydW5jYXRlIH0gZnJvbSAnLi4vLi4vdXRpbHMvZm9ybWF0LmpzJ1xuaW1wb3J0IHR5cGUgeyBPdXRwdXQgfSBmcm9tICcuL1dlYkZldGNoVG9vbC5qcydcblxuZXhwb3J0IGZ1bmN0aW9uIHJlbmRlclRvb2xVc2VNZXNzYWdlKFxuICB7IHVybCwgcHJvbXB0IH06IFBhcnRpYWw8eyB1cmw6IHN0cmluZzsgcHJvbXB0OiBzdHJpbmcgfT4sXG4gIHsgdmVyYm9zZSB9OiB7IHRoZW1lPzogc3RyaW5nOyB2ZXJib3NlOiBib29sZWFuIH0sXG4pOiBSZWFjdC5SZWFjdE5vZGUge1xuICBpZiAoIXVybCkge1xuICAgIHJldHVybiBudWxsXG4gIH1cbiAgaWYgKHZlcmJvc2UpIHtcbiAgICByZXR1cm4gYHVybDogXCIke3VybH1cIiR7dmVyYm9zZSAmJiBwcm9tcHQgPyBgLCBwcm9tcHQ6IFwiJHtwcm9tcHR9XCJgIDogJyd9YFxuICB9XG4gIHJldHVybiB1cmxcbn1cblxuZXhwb3J0IGZ1bmN0aW9uIHJlbmRlclRvb2xVc2VQcm9ncmVzc01lc3NhZ2UoKTogUmVhY3QuUmVhY3ROb2RlIHtcbiAgcmV0dXJuIChcbiAgICA8TWVzc2FnZVJlc3BvbnNlIGhlaWdodD17MX0+XG4gICAgICA8VGV4dCBkaW1Db2xvcj5GZXRjaGluZ+KApjwvVGV4dD5cbiAgICA8L01lc3NhZ2VSZXNwb25zZT5cbiAgKVxufVxuXG5leHBvcnQgZnVuY3Rpb24gcmVuZGVyVG9vbFJlc3VsdE1lc3NhZ2UoXG4gIHsgYnl0ZXMsIGNvZGUsIGNvZGVUZXh0LCByZXN1bHQgfTogT3V0cHV0LFxuICBfcHJvZ3Jlc3NNZXNzYWdlc0Zvck1lc3NhZ2U6IFByb2dyZXNzTWVzc2FnZTxUb29sUHJvZ3Jlc3NEYXRhPltdLFxuICB7IHZlcmJvc2UgfTogeyB2ZXJib3NlOiBib29sZWFuIH0sXG4pOiBSZWFjdC5SZWFjdE5vZGUge1xuICBjb25zdCBmb3JtYXR0ZWRTaXplID0gZm9ybWF0RmlsZVNpemUoYnl0ZXMpXG4gIGlmICh2ZXJib3NlKSB7XG4gICAgcmV0dXJuIChcbiAgICAgIDxCb3ggZmxleERpcmVjdGlvbj1cImNvbHVtblwiPlxuICAgICAgICA8TWVzc2FnZVJlc3BvbnNlIGhlaWdodD17MX0+XG4gICAgICAgICAgPFRleHQ+XG4gICAgICAgICAgICBSZWNlaXZlZCA8VGV4dCBib2xkPntmb3JtYXR0ZWRTaXplfTwvVGV4dD4gKHtjb2RlfSB7Y29kZVRleHR9KVxuICAgICAgICAgIDwvVGV4dD5cbiAgICAgICAgPC9NZXNzYWdlUmVzcG9uc2U+XG4gICAgICAgIDxCb3ggZmxleERpcmVjdGlvbj1cImNvbHVtblwiPlxuICAgICAgICAgIDxUZXh0PntyZXN1bHR9PC9UZXh0PlxuICAgICAgICA8L0JveD5cbiAgICAgIDwvQm94PlxuICAgIClcbiAgfVxuICByZXR1cm4gKFxuICAgIDxNZXNzYWdlUmVzcG9uc2UgaGVpZ2h0PXsxfT5cbiAgICAgIDxUZXh0PlxuICAgICAgICBSZWNlaXZlZCA8VGV4dCBib2xkPntmb3JtYXR0ZWRTaXplfTwvVGV4dD4gKHtjb2RlfSB7Y29kZVRleHR9KVxuICAgICAgPC9UZXh0PlxuICAgIDwvTWVzc2FnZVJlc3BvbnNlPlxuICApXG59XG5cbmV4cG9ydCBmdW5jdGlvbiBnZXRUb29sVXNlU3VtbWFyeShcbiAgaW5wdXQ6IFBhcnRpYWw8eyB1cmw6IHN0cmluZzsgcHJvbXB0OiBzdHJpbmcgfT4gfCB1bmRlZmluZWQsXG4pOiBzdHJpbmcgfCBudWxsIHtcbiAgaWYgKCFpbnB1dD8udXJsKSB7XG4gICAgcmV0dXJuIG51bGxcbiAgfVxuICByZXR1cm4gdHJ1bmNhdGUoaW5wdXQudXJsLCBUT09MX1NVTU1BUllfTUFYX0xFTkdUSClcbn1cbiJdLCJtYXBwaW5ncyI6IkFBQUEsT0FBT0EsS0FBSyxNQUFNLE9BQU87QUFDekIsU0FBU0MsZUFBZSxRQUFRLHFDQUFxQztBQUNyRSxTQUFTQyx1QkFBdUIsUUFBUSwrQkFBK0I7QUFDdkUsU0FBU0MsR0FBRyxFQUFFQyxJQUFJLFFBQVEsY0FBYztBQUN4QyxjQUFjQyxnQkFBZ0IsUUFBUSxlQUFlO0FBQ3JELGNBQWNDLGVBQWUsUUFBUSx3QkFBd0I7QUFDN0QsU0FBU0MsY0FBYyxFQUFFQyxRQUFRLFFBQVEsdUJBQXVCO0FBQ2hFLGNBQWND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

package/tools/WebFetchTool/WebFetchTool.ts

@@ -0,0 +1,318 @@
+import { z } from 'zod/v4'
+import { buildTool, type ToolDef } from '../../Tool.js'
+import type { PermissionUpdate } from '../../types/permissions.js'
+import { formatFileSize } from '../../utils/format.js'
+import { lazySchema } from '../../utils/lazySchema.js'
+import type { PermissionDecision } from '../../utils/permissions/PermissionResult.js'
+import { getRuleByContentsForTool } from '../../utils/permissions/permissions.js'
+import { isPreapprovedHost } from './preapproved.js'
+import { DESCRIPTION, WEB_FETCH_TOOL_NAME } from './prompt.js'
+import {
+  getToolUseSummary,
+  renderToolResultMessage,
+  renderToolUseMessage,
+  renderToolUseProgressMessage,
+} from './UI.js'
+import {
+  applyPromptToMarkdown,
+  type FetchedContent,
+  getURLMarkdownContent,
+  isPreapprovedUrl,
+  MAX_MARKDOWN_LENGTH,
+} from './utils.js'
+
+const inputSchema = lazySchema(() =>
+  z.strictObject({
+    url: z.string().url().describe('The URL to fetch content from'),
+    prompt: z.string().describe('The prompt to run on the fetched content'),
+  }),
+)
+type InputSchema = ReturnType<typeof inputSchema>
+
+const outputSchema = lazySchema(() =>
+  z.object({
+    bytes: z.number().describe('Size of the fetched content in bytes'),
+    code: z.number().describe('HTTP response code'),
+    codeText: z.string().describe('HTTP response code text'),
+    result: z
+      .string()
+      .describe('Processed result from applying the prompt to the content'),
+    durationMs: z
+      .number()
+      .describe('Time taken to fetch and process the content'),
+    url: z.string().describe('The URL that was fetched'),
+  }),
+)
+type OutputSchema = ReturnType<typeof outputSchema>
+
+export type Output = z.infer<OutputSchema>
+
+function webFetchToolInputToPermissionRuleContent(input: {
+  [k: string]: unknown
+}): string {
+  try {
+    const parsedInput = WebFetchTool.inputSchema.safeParse(input)
+    if (!parsedInput.success) {
+      return `input:${input.toString()}`
+    }
+    const { url } = parsedInput.data
+    const hostname = new URL(url).hostname
+    return `domain:${hostname}`
+  } catch {
+    return `input:${input.toString()}`
+  }
+}
+
+export const WebFetchTool = buildTool({
+  name: WEB_FETCH_TOOL_NAME,
+  searchHint: 'fetch and extract content from a URL',
+  // 100K chars - tool result persistence threshold
+  maxResultSizeChars: 100_000,
+  shouldDefer: true,
+  async description(input) {
+    const { url } = input as { url: string }
+    try {
+      const hostname = new URL(url).hostname
+      return `Claude wants to fetch content from ${hostname}`
+    } catch {
+      return `Claude wants to fetch content from this URL`
+    }
+  },
+  userFacingName() {
+    return 'Fetch'
+  },
+  getToolUseSummary,
+  getActivityDescription(input) {
+    const summary = getToolUseSummary(input)
+    return summary ? `Fetching ${summary}` : 'Fetching web page'
+  },
+  get inputSchema(): InputSchema {
+    return inputSchema()
+  },
+  get outputSchema(): OutputSchema {
+    return outputSchema()
+  },
+  isConcurrencySafe() {
+    return true
+  },
+  isReadOnly() {
+    return true
+  },
+  toAutoClassifierInput(input) {
+    return input.prompt ? `${input.url}: ${input.prompt}` : input.url
+  },
+  async checkPermissions(input, context): Promise<PermissionDecision> {
+    const appState = context.getAppState()
+    const permissionContext = appState.toolPermissionContext
+
+    // Check if the hostname is in the preapproved list
+    try {
+      const { url } = input as { url: string }
+      const parsedUrl = new URL(url)
+      if (isPreapprovedHost(parsedUrl.hostname, parsedUrl.pathname)) {
+        return {
+          behavior: 'allow',
+          updatedInput: input,
+          decisionReason: { type: 'other', reason: 'Preapproved host' },
+        }
+      }
+    } catch {
+      // If URL parsing fails, continue with normal permission checks
+    }
+
+    // Check for a rule specific to the tool input (matching hostname)
+    const ruleContent = webFetchToolInputToPermissionRuleContent(input)
+
+    const denyRule = getRuleByContentsForTool(
+      permissionContext,
+      WebFetchTool,
+      'deny',
+    ).get(ruleContent)
+    if (denyRule) {
+      return {
+        behavior: 'deny',
+        message: `${WebFetchTool.name} denied access to ${ruleContent}.`,
+        decisionReason: {
+          type: 'rule',
+          rule: denyRule,
+        },
+      }
+    }
+
+    const askRule = getRuleByContentsForTool(
+      permissionContext,
+      WebFetchTool,
+      'ask',
+    ).get(ruleContent)
+    if (askRule) {
+      return {
+        behavior: 'ask',
+        message: `Claude requested permissions to use ${WebFetchTool.name}, but you haven't granted it yet.`,
+        decisionReason: {
+          type: 'rule',
+          rule: askRule,
+        },
+        suggestions: buildSuggestions(ruleContent),
+      }
+    }
+
+    const allowRule = getRuleByContentsForTool(
+      permissionContext,
+      WebFetchTool,
+      'allow',
+    ).get(ruleContent)
+    if (allowRule) {
+      return {
+        behavior: 'allow',
+        updatedInput: input,
+        decisionReason: {
+          type: 'rule',
+          rule: allowRule,
+        },
+      }
+    }
+
+    return {
+      behavior: 'ask',
+      message: `Claude requested permissions to use ${WebFetchTool.name}, but you haven't granted it yet.`,
+      suggestions: buildSuggestions(ruleContent),
+    }
+  },
+  async prompt(_options) {
+    // Always include the auth warning regardless of whether ToolSearch is
+    // currently in the tools list. Conditionally toggling this prefix based
+    // on ToolSearch availability caused the tool description to flicker
+    // between SDK query() calls (when ToolSearch enablement varies due to
+    // MCP tool count thresholds), invalidating the Anthropic API prompt
+    // cache on each toggle — two consecutive cache misses per flicker event.
+    return `IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, look for a specialized MCP tool that provides authenticated access.
+${DESCRIPTION}`
+  },
+  async validateInput(input) {
+    const { url } = input
+    try {
+      new URL(url)
+    } catch {
+      return {
+        result: false,
+        message: `Error: Invalid URL "${url}". The URL provided could not be parsed.`,
+        meta: { reason: 'invalid_url' },
+        errorCode: 1,
+      }
+    }
+    return { result: true }
+  },
+  renderToolUseMessage,
+  renderToolUseProgressMessage,
+  renderToolResultMessage,
+  async call(
+    { url, prompt },
+    { abortController, options: { isNonInteractiveSession } },
+  ) {
+    const start = Date.now()
+
+    const response = await getURLMarkdownContent(url, abortController)
+
+    // Check if we got a redirect to a different host
+    if ('type' in response && response.type === 'redirect') {
+      const statusText =
+        response.statusCode === 301
+          ? 'Moved Permanently'
+          : response.statusCode === 308
+            ? 'Permanent Redirect'
+            : response.statusCode === 307
+              ? 'Temporary Redirect'
+              : 'Found'
+
+      const message = `REDIRECT DETECTED: The URL redirects to a different host.
+
+Original URL: ${response.originalUrl}
+Redirect URL: ${response.redirectUrl}
+Status: ${response.statusCode} ${statusText}
+
+To complete your request, I need to fetch content from the redirected URL. Please use WebFetch again with these parameters:
+- url: "${response.redirectUrl}"
+- prompt: "${prompt}"`
+
+      const output: Output = {
+        bytes: Buffer.byteLength(message),
+        code: response.statusCode,
+        codeText: statusText,
+        result: message,
+        durationMs: Date.now() - start,
+        url,
+      }
+
+      return {
+        data: output,
+      }
+    }
+
+    const {
+      content,
+      bytes,
+      code,
+      codeText,
+      contentType,
+      persistedPath,
+      persistedSize,
+    } = response as FetchedContent
+
+    const isPreapproved = isPreapprovedUrl(url)
+
+    let result: string
+    if (
+      isPreapproved &&
+      contentType.includes('text/markdown') &&
+      content.length < MAX_MARKDOWN_LENGTH
+    ) {
+      result = content
+    } else {
+      result = await applyPromptToMarkdown(
+        prompt,
+        content,
+        abortController.signal,
+        isNonInteractiveSession,
+        isPreapproved,
+      )
+    }
+
+    // Binary content (PDFs, etc.) was additionally saved to disk with a
+    // mime-derived extension. Note it so Claude can inspect the raw file
+    // if the Haiku summary above isn't enough.
+    if (persistedPath) {
+      result += `\n\n[Binary content (${contentType}, ${formatFileSize(persistedSize ?? bytes)}) also saved to ${persistedPath}]`
+    }
+
+    const output: Output = {
+      bytes,
+      code,
+      codeText,
+      result,
+      durationMs: Date.now() - start,
+      url,
+    }
+
+    return {
+      data: output,
+    }
+  },
+  mapToolResultToToolResultBlockParam({ result }, toolUseID) {
+    return {
+      tool_use_id: toolUseID,
+      type: 'tool_result',
+      content: result,
+    }
+  },
+} satisfies ToolDef<InputSchema, Output>)
+
+function buildSuggestions(ruleContent: string): PermissionUpdate[] {
+  return [
+    {
+      type: 'addRules',
+      destination: 'localSettings',
+      rules: [{ toolName: WEB_FETCH_TOOL_NAME, ruleContent }],
+      behavior: 'allow',
+    },
+  ]
+}

package/tools/WebFetchTool/preapproved.ts

@@ -0,0 +1,166 @@
+// For legal and security concerns, we typically only allow Web Fetch to access
+// domains that the user has provided in some form. However, we make an
+// exception for a list of preapproved domains that are code-related.
+//
+// SECURITY WARNING: These preapproved domains are ONLY for WebFetch (GET requests only).
+// The sandbox system deliberately does NOT inherit this list for network restrictions,
+// as arbitrary network access (POST, uploads, etc.) to these domains could enable
+// data exfiltration. Some domains like huggingface.co, kaggle.com, and nuget.org
+// allow file uploads and would be dangerous for unrestricted network access.
+//
+// See test/utils/sandbox/webfetch-preapproved-separation.test.ts for verification
+// that sandbox network restrictions require explicit user permission rules.
+
+export const PREAPPROVED_HOSTS = new Set([
+  // Anthropic
+  'platform.claude.com',
+  'code.claude.com',
+  'modelcontextprotocol.io',
+  'github.com/anthropics',
+  'agentskills.io',
+
+  // Top Programming Languages
+  'docs.python.org', // Python
+  'en.cppreference.com', // C/C++ reference
+  'docs.oracle.com', // Java
+  'learn.microsoft.com', // C#/.NET
+  'developer.mozilla.org', // JavaScript/Web APIs (MDN)
+  'go.dev', // Go
+  'pkg.go.dev', // Go docs
+  'www.php.net', // PHP
+  'docs.swift.org', // Swift
+  'kotlinlang.org', // Kotlin
+  'ruby-doc.org', // Ruby
+  'doc.rust-lang.org', // Rust
+  'www.typescriptlang.org', // TypeScript
+
+  // Web & JavaScript Frameworks/Libraries
+  'react.dev', // React
+  'angular.io', // Angular
+  'vuejs.org', // Vue.js
+  'nextjs.org', // Next.js
+  'expressjs.com', // Express.js
+  'nodejs.org', // Node.js
+  'bun.sh', // Bun
+  'jquery.com', // jQuery
+  'getbootstrap.com', // Bootstrap
+  'tailwindcss.com', // Tailwind CSS
+  'd3js.org', // D3.js
+  'threejs.org', // Three.js
+  'redux.js.org', // Redux
+  'webpack.js.org', // Webpack
+  'jestjs.io', // Jest
+  'reactrouter.com', // React Router
+
+  // Python Frameworks & Libraries
+  'docs.djangoproject.com', // Django
+  'flask.palletsprojects.com', // Flask
+  'fastapi.tiangolo.com', // FastAPI
+  'pandas.pydata.org', // Pandas
+  'numpy.org', // NumPy
+  'www.tensorflow.org', // TensorFlow
+  'pytorch.org', // PyTorch
+  'scikit-learn.org', // Scikit-learn
+  'matplotlib.org', // Matplotlib
+  'requests.readthedocs.io', // Requests
+  'jupyter.org', // Jupyter
+
+  // PHP Frameworks
+  'laravel.com', // Laravel
+  'symfony.com', // Symfony
+  'wordpress.org', // WordPress
+
+  // Java Frameworks & Libraries
+  'docs.spring.io', // Spring
+  'hibernate.org', // Hibernate
+  'tomcat.apache.org', // Tomcat
+  'gradle.org', // Gradle
+  'maven.apache.org', // Maven
+
+  // .NET & C# Frameworks
+  'asp.net', // ASP.NET
+  'dotnet.microsoft.com', // .NET
+  'nuget.org', // NuGet
+  'blazor.net', // Blazor
+
+  // Mobile Development
+  'reactnative.dev', // React Native
+  'docs.flutter.dev', // Flutter
+  'developer.apple.com', // iOS/macOS
+  'developer.android.com', // Android
+
+  // Data Science & Machine Learning
+  'keras.io', // Keras
+  'spark.apache.org', // Apache Spark
+  'huggingface.co', // Hugging Face
+  'www.kaggle.com', // Kaggle
+
+  // Databases
+  'www.mongodb.com', // MongoDB
+  'redis.io', // Redis
+  'www.postgresql.org', // PostgreSQL
+  'dev.mysql.com', // MySQL
+  'www.sqlite.org', // SQLite
+  'graphql.org', // GraphQL
+  'prisma.io', // Prisma
+
+  // Cloud & DevOps
+  'docs.aws.amazon.com', // AWS
+  'cloud.google.com', // Google Cloud
+  'learn.microsoft.com', // Azure
+  'kubernetes.io', // Kubernetes
+  'www.docker.com', // Docker
+  'www.terraform.io', // Terraform
+  'www.ansible.com', // Ansible
+  'vercel.com/docs', // Vercel
+  'docs.netlify.com', // Netlify
+  'devcenter.heroku.com', // Heroku
+
+  // Testing & Monitoring
+  'cypress.io', // Cypress
+  'selenium.dev', // Selenium
+
+  // Game Development
+  'docs.unity.com', // Unity
+  'docs.unrealengine.com', // Unreal Engine
+
+  // Other Essential Tools
+  'git-scm.com', // Git
+  'nginx.org', // Nginx
+  'httpd.apache.org', // Apache HTTP Server
+])
+
+// Split once at module load so lookups are O(1) Set.has() for the common
+// hostname-only case, falling back to a small per-host path-prefix list
+// for the handful of path-scoped entries (e.g., "github.com/anthropics").
+const { HOSTNAME_ONLY, PATH_PREFIXES } = (() => {
+  const hosts = new Set<string>()
+  const paths = new Map<string, string[]>()
+  for (const entry of PREAPPROVED_HOSTS) {
+    const slash = entry.indexOf('/')
+    if (slash === -1) {
+      hosts.add(entry)
+    } else {
+      const host = entry.slice(0, slash)
+      const path = entry.slice(slash)
+      const prefixes = paths.get(host)
+      if (prefixes) prefixes.push(path)
+      else paths.set(host, [path])
+    }
+  }
+  return { HOSTNAME_ONLY: hosts, PATH_PREFIXES: paths }
+})()
+
+export function isPreapprovedHost(hostname: string, pathname: string): boolean {
+  if (HOSTNAME_ONLY.has(hostname)) return true
+  const prefixes = PATH_PREFIXES.get(hostname)
+  if (prefixes) {
+    for (const p of prefixes) {
+      // Enforce path segment boundaries: "/anthropics" must not match
+      // "/anthropics-evil/malware". Only exact match or a "/" after the
+      // prefix is allowed.
+      if (pathname === p || pathname.startsWith(p + '/')) return true
+    }
+  }
+  return false
+}