@xortex/xcode 3.0.0

package/utils/hooks/execAgentHook.ts

@@ -0,0 +1,339 @@
+import { randomUUID } from 'crypto'
+import type { HookEvent } from 'src/entrypoints/agentSdkTypes.js'
+import { query } from '../../query.js'
+import { logEvent } from '../../services/analytics/index.js'
+import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from '../../services/analytics/metadata.js'
+import type { ToolUseContext } from '../../Tool.js'
+import { type Tool, toolMatchesName } from '../../Tool.js'
+import { SYNTHETIC_OUTPUT_TOOL_NAME } from '../../tools/SyntheticOutputTool/SyntheticOutputTool.js'
+import { ALL_AGENT_DISALLOWED_TOOLS } from '../../tools.js'
+import { asAgentId } from '../../types/ids.js'
+import type { Message } from '../../types/message.js'
+import { createAbortController } from '../abortController.js'
+import { createAttachmentMessage } from '../attachments.js'
+import { createCombinedAbortSignal } from '../combinedAbortSignal.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage } from '../errors.js'
+import type { HookResult } from '../hooks.js'
+import { createUserMessage, handleMessageFromStream } from '../messages.js'
+import { getSmallFastModel } from '../model/model.js'
+import { hasPermissionsToUseTool } from '../permissions/permissions.js'
+import { getAgentTranscriptPath, getTranscriptPath } from '../sessionStorage.js'
+import type { AgentHook } from '../settings/types.js'
+import { jsonStringify } from '../slowOperations.js'
+import { asSystemPrompt } from '../systemPromptType.js'
+import {
+  addArgumentsToPrompt,
+  createStructuredOutputTool,
+  hookResponseSchema,
+  registerStructuredOutputEnforcement,
+} from './hookHelpers.js'
+import { clearSessionHooks } from './sessionHooks.js'
+
+/**
+ * Execute an agent-based hook using a multi-turn LLM query
+ */
+export async function execAgentHook(
+  hook: AgentHook,
+  hookName: string,
+  hookEvent: HookEvent,
+  jsonInput: string,
+  signal: AbortSignal,
+  toolUseContext: ToolUseContext,
+  toolUseID: string | undefined,
+  // Kept for signature stability with the other exec*Hook functions.
+  // Was used by hook.prompt(messages) before the .transform() was removed
+  // (CC-79) — the only consumer of that was ExitPlanModeV2Tool's
+  // programmatic construction, since refactored into VerifyPlanExecutionTool.
+  _messages: Message[],
+  agentName?: string,
+): Promise<HookResult> {
+  const effectiveToolUseID = toolUseID || `hook-${randomUUID()}`
+
+  // Get transcript path from context
+  const transcriptPath = toolUseContext.agentId
+    ? getAgentTranscriptPath(toolUseContext.agentId)
+    : getTranscriptPath()
+  const hookStartTime = Date.now()
+  try {
+    // Replace $ARGUMENTS with the JSON input
+    const processedPrompt = addArgumentsToPrompt(hook.prompt, jsonInput)
+    logForDebugging(
+      `Hooks: Processing agent hook with prompt: ${processedPrompt}`,
+    )
+
+    // Create user message directly - no need for processUserInput which would
+    // trigger UserPromptSubmit hooks and cause infinite recursion
+    const userMessage = createUserMessage({ content: processedPrompt })
+    const agentMessages = [userMessage]
+
+    logForDebugging(
+      `Hooks: Starting agent query with ${agentMessages.length} messages`,
+    )
+
+    // Setup timeout and combine with parent signal
+    const hookTimeoutMs = hook.timeout ? hook.timeout * 1000 : 60000
+    const hookAbortController = createAbortController()
+
+    // Combine parent signal with timeout, and have it abort our controller
+    const { signal: parentTimeoutSignal, cleanup: cleanupCombinedSignal } =
+      createCombinedAbortSignal(signal, { timeoutMs: hookTimeoutMs })
+    const onParentTimeout = () => hookAbortController.abort()
+    parentTimeoutSignal.addEventListener('abort', onParentTimeout)
+
+    // Combined signal is just our controller's signal now
+    const combinedSignal = hookAbortController.signal
+
+    try {
+      // Create StructuredOutput tool with our schema
+      const structuredOutputTool = createStructuredOutputTool()
+
+      // Filter out any existing StructuredOutput tool to avoid duplicates with different schemas
+      // (e.g., when parent context has a StructuredOutput tool from --json-schema flag)
+      const filteredTools = toolUseContext.options.tools.filter(
+        tool => !toolMatchesName(tool, SYNTHETIC_OUTPUT_TOOL_NAME),
+      )
+
+      // Use all available tools plus our structured output tool
+      // Filter out disallowed agent tools to prevent stop hook agents from spawning subagents
+      // or entering plan mode, and filter out duplicate StructuredOutput tools
+      const tools: Tool[] = [
+        ...filteredTools.filter(
+          tool => !ALL_AGENT_DISALLOWED_TOOLS.has(tool.name),
+        ),
+        structuredOutputTool,
+      ]
+
+      const systemPrompt = asSystemPrompt([
+        `You are verifying a stop condition in Claude Code. Your task is to verify that the agent completed the given plan. The conversation transcript is available at: ${transcriptPath}\nYou can read this file to analyze the conversation history if needed.
+
+Use the available tools to inspect the codebase and verify the condition.
+Use as few steps as possible - be efficient and direct.
+
+When done, return your result using the ${SYNTHETIC_OUTPUT_TOOL_NAME} tool with:
+- ok: true if the condition is met
+- ok: false with reason if the condition is not met`,
+      ])
+
+      const model = hook.model ?? getSmallFastModel()
+      const MAX_AGENT_TURNS = 50
+
+      // Create unique agentId for this hook agent
+      const hookAgentId = asAgentId(`hook-agent-${randomUUID()}`)
+
+      // Create a modified toolUseContext for the agent
+      const agentToolUseContext: ToolUseContext = {
+        ...toolUseContext,
+        agentId: hookAgentId,
+        abortController: hookAbortController,
+        options: {
+          ...toolUseContext.options,
+          tools,
+          mainLoopModel: model,
+          isNonInteractiveSession: true,
+          thinkingConfig: { type: 'disabled' as const },
+        },
+        setInProgressToolUseIDs: () => {},
+        getAppState() {
+          const appState = toolUseContext.getAppState()
+          // Add session rule to allow reading transcript file
+          const existingSessionRules =
+            appState.toolPermissionContext.alwaysAllowRules.session ?? []
+          return {
+            ...appState,
+            toolPermissionContext: {
+              ...appState.toolPermissionContext,
+              mode: 'dontAsk' as const,
+              alwaysAllowRules: {
+                ...appState.toolPermissionContext.alwaysAllowRules,
+                session: [...existingSessionRules, `Read(/${transcriptPath})`],
+              },
+            },
+          }
+        },
+      }
+
+      // Register a session-level stop hook to enforce structured output
+      registerStructuredOutputEnforcement(
+        toolUseContext.setAppState,
+        hookAgentId,
+      )
+
+      let structuredOutputResult: { ok: boolean; reason?: string } | null = null
+      let turnCount = 0
+      let hitMaxTurns = false
+
+      // Use query() for multi-turn execution
+      for await (const message of query({
+        messages: agentMessages,
+        systemPrompt,
+        userContext: {},
+        systemContext: {},
+        canUseTool: hasPermissionsToUseTool,
+        toolUseContext: agentToolUseContext,
+        querySource: 'hook_agent',
+      })) {
+        // Process stream events to update response length in the spinner
+        handleMessageFromStream(
+          message,
+          () => {}, // onMessage - we handle messages below
+          newContent =>
+            toolUseContext.setResponseLength(
+              length => length + newContent.length,
+            ),
+          toolUseContext.setStreamMode ?? (() => {}),
+          () => {}, // onStreamingToolUses - not needed for hooks
+        )
+
+        // Skip streaming events for further processing
+        if (
+          message.type === 'stream_event' ||
+          message.type === 'stream_request_start'
+        ) {
+          continue
+        }
+
+        // Count assistant turns
+        if (message.type === 'assistant') {
+          turnCount++
+
+          // Check if we've hit the turn limit
+          if (turnCount >= MAX_AGENT_TURNS) {
+            hitMaxTurns = true
+            logForDebugging(
+              `Hooks: Agent turn ${turnCount} hit max turns, aborting`,
+            )
+            hookAbortController.abort()
+            break
+          }
+        }
+
+        // Check for structured output in attachments
+        if (
+          message.type === 'attachment' &&
+          message.attachment.type === 'structured_output'
+        ) {
+          const parsed = hookResponseSchema().safeParse(message.attachment.data)
+          if (parsed.success) {
+            structuredOutputResult = parsed.data
+            logForDebugging(
+              `Hooks: Got structured output: ${jsonStringify(structuredOutputResult)}`,
+            )
+            // Got structured output, abort and exit
+            hookAbortController.abort()
+            break
+          }
+        }
+      }
+
+      parentTimeoutSignal.removeEventListener('abort', onParentTimeout)
+      cleanupCombinedSignal()
+
+      // Clean up the session hook we registered for this agent
+      clearSessionHooks(toolUseContext.setAppState, hookAgentId)
+
+      // Check if we got a result
+      if (!structuredOutputResult) {
+        // If we hit max turns, just log and return cancelled (no UI message)
+        if (hitMaxTurns) {
+          logForDebugging(
+            `Hooks: Agent hook did not complete within ${MAX_AGENT_TURNS} turns`,
+          )
+          logEvent('tengu_agent_stop_hook_max_turns', {
+            durationMs: Date.now() - hookStartTime,
+            turnCount,
+            agentName:
+              agentName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+          })
+          return {
+            hook,
+            outcome: 'cancelled',
+          }
+        }
+
+        // For other cases (e.g., agent finished without calling structured output tool),
+        // just log and return cancelled (don't show error to user)
+        logForDebugging(`Hooks: Agent hook did not return structured output`)
+        logEvent('tengu_agent_stop_hook_error', {
+          durationMs: Date.now() - hookStartTime,
+          turnCount,
+          errorType: 1, // 1 = no structured output
+          agentName:
+            agentName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        })
+        return {
+          hook,
+          outcome: 'cancelled',
+        }
+      }
+
+      // Return result based on structured output
+      if (!structuredOutputResult.ok) {
+        logForDebugging(
+          `Hooks: Agent hook condition was not met: ${structuredOutputResult.reason}`,
+        )
+        return {
+          hook,
+          outcome: 'blocking',
+          blockingError: {
+            blockingError: `Agent hook condition was not met: ${structuredOutputResult.reason}`,
+            command: hook.prompt,
+          },
+        }
+      }
+
+      // Condition was met
+      logForDebugging(`Hooks: Agent hook condition was met`)
+      logEvent('tengu_agent_stop_hook_success', {
+        durationMs: Date.now() - hookStartTime,
+        turnCount,
+        agentName:
+          agentName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      })
+      return {
+        hook,
+        outcome: 'success',
+        message: createAttachmentMessage({
+          type: 'hook_success',
+          hookName,
+          toolUseID: effectiveToolUseID,
+          hookEvent,
+          content: '',
+        }),
+      }
+    } catch (error) {
+      parentTimeoutSignal.removeEventListener('abort', onParentTimeout)
+      cleanupCombinedSignal()
+
+      if (combinedSignal.aborted) {
+        return {
+          hook,
+          outcome: 'cancelled',
+        }
+      }
+      throw error
+    }
+  } catch (error) {
+    const errorMsg = errorMessage(error)
+    logForDebugging(`Hooks: Agent hook error: ${errorMsg}`)
+    logEvent('tengu_agent_stop_hook_error', {
+      durationMs: Date.now() - hookStartTime,
+      errorType: 2, // 2 = general error
+      agentName:
+        agentName as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    })
+    return {
+      hook,
+      outcome: 'non_blocking_error',
+      message: createAttachmentMessage({
+        type: 'hook_non_blocking_error',
+        hookName,
+        toolUseID: effectiveToolUseID,
+        hookEvent,
+        stderr: `Error executing agent hook: ${errorMsg}`,
+        stdout: '',
+        exitCode: 1,
+      }),
+    }
+  }
+}

package/utils/hooks/execHttpHook.ts

@@ -0,0 +1,242 @@
+import axios from 'src/utils/axios.js'
+import type { HookEvent } from 'src/entrypoints/agentSdkTypes.js'
+import { createCombinedAbortSignal } from '../combinedAbortSignal.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage } from '../errors.js'
+import { getProxyUrl, shouldBypassProxy } from '../proxy.js'
+// Import as namespace so spyOn works in tests (direct imports bypass spies)
+import * as settingsModule from '../settings/settings.js'
+import type { HttpHook } from '../settings/types.js'
+import { ssrfGuardedLookup } from './ssrfGuard.js'
+
+const DEFAULT_HTTP_HOOK_TIMEOUT_MS = 10 * 60 * 1000 // 10 minutes (matches TOOL_HOOK_EXECUTION_TIMEOUT_MS)
+
+/**
+ * Get the sandbox proxy config for routing HTTP hook requests through the
+ * sandbox network proxy when sandboxing is enabled.
+ *
+ * Uses dynamic import to avoid a static import cycle
+ * (sandbox-adapter -> settings -> ... -> hooks -> execHttpHook).
+ */
+async function getSandboxProxyConfig(): Promise<
+  { host: string; port: number; protocol: string } | undefined
+> {
+  const { SandboxManager } = await import('../sandbox/sandbox-adapter.js')
+
+  if (!SandboxManager.isSandboxingEnabled()) {
+    return undefined
+  }
+
+  // Wait for the sandbox network proxy to finish initializing. In REPL mode,
+  // SandboxManager.initialize() is fire-and-forget so the proxy may not be
+  // ready yet when the first hook fires.
+  await SandboxManager.waitForNetworkInitialization()
+
+  const proxyPort = SandboxManager.getProxyPort()
+  if (!proxyPort) {
+    return undefined
+  }
+
+  return { host: '127.0.0.1', port: proxyPort, protocol: 'http' }
+}
+
+/**
+ * Read HTTP hook allowlist restrictions from merged settings (all sources).
+ * Follows the allowedMcpServers precedent: arrays concatenate across sources.
+ * When allowManagedHooksOnly is set in managed settings, only admin-defined
+ * hooks run anyway, so no separate lock-down boolean is needed here.
+ */
+function getHttpHookPolicy(): {
+  allowedUrls: string[] | undefined
+  allowedEnvVars: string[] | undefined
+} {
+  const settings = settingsModule.getInitialSettings()
+  return {
+    allowedUrls: settings.allowedHttpHookUrls,
+    allowedEnvVars: settings.httpHookAllowedEnvVars,
+  }
+}
+
+/**
+ * Match a URL against a pattern with * as a wildcard (any characters).
+ * Same semantics as the MCP server allowlist patterns.
+ */
+function urlMatchesPattern(url: string, pattern: string): boolean {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+  const regexStr = escaped.replace(/\*/g, '.*')
+  return new RegExp(`^${regexStr}$`).test(url)
+}
+
+/**
+ * Strip CR, LF, and NUL bytes from a header value to prevent HTTP header
+ * injection (CRLF injection) via env var values or hook-configured header
+ * templates. A malicious env var like "token\r\nX-Evil: 1" would otherwise
+ * inject a second header into the request.
+ */
+function sanitizeHeaderValue(value: string): string {
+  // eslint-disable-next-line no-control-regex
+  return value.replace(/[\r\n\x00]/g, '')
+}
+
+/**
+ * Interpolate $VAR_NAME and ${VAR_NAME} patterns in a string using process.env,
+ * but only for variable names present in the allowlist. References to variables
+ * not in the allowlist are replaced with empty strings to prevent exfiltration
+ * of secrets via project-configured HTTP hooks.
+ *
+ * The result is sanitized to strip CR/LF/NUL bytes to prevent header injection.
+ */
+function interpolateEnvVars(
+  value: string,
+  allowedEnvVars: ReadonlySet<string>,
+): string {
+  const interpolated = value.replace(
+    /\$\{([A-Z_][A-Z0-9_]*)\}|\$([A-Z_][A-Z0-9_]*)/g,
+    (_, braced, unbraced) => {
+      const varName = braced ?? unbraced
+      if (!allowedEnvVars.has(varName)) {
+        logForDebugging(
+          `Hooks: env var $${varName} not in allowedEnvVars, skipping interpolation`,
+          { level: 'warn' },
+        )
+        return ''
+      }
+      return process.env[varName] ?? ''
+    },
+  )
+  return sanitizeHeaderValue(interpolated)
+}
+
+/**
+ * Execute an HTTP hook by POSTing the hook input JSON to the configured URL.
+ * Returns the raw response for the caller to interpret.
+ *
+ * When sandboxing is enabled, requests are routed through the sandbox network
+ * proxy which enforces the domain allowlist. The proxy returns HTTP 403 for
+ * blocked domains.
+ *
+ * Header values support $VAR_NAME and ${VAR_NAME} env var interpolation so that
+ * secrets (e.g. "Authorization: Bearer $MY_TOKEN") are not stored in settings.json.
+ * Only env vars explicitly listed in the hook's `allowedEnvVars` array are resolved;
+ * all other references are replaced with empty strings.
+ */
+export async function execHttpHook(
+  hook: HttpHook,
+  _hookEvent: HookEvent,
+  jsonInput: string,
+  signal?: AbortSignal,
+): Promise<{
+  ok: boolean
+  statusCode?: number
+  body: string
+  error?: string
+  aborted?: boolean
+}> {
+  // Enforce URL allowlist before any I/O. Follows allowedMcpServers semantics:
+  // undefined → no restriction; [] → block all; non-empty → must match a pattern.
+  const policy = getHttpHookPolicy()
+  if (policy.allowedUrls !== undefined) {
+    const matched = policy.allowedUrls.some(p => urlMatchesPattern(hook.url, p))
+    if (!matched) {
+      const msg = `HTTP hook blocked: ${hook.url} does not match any pattern in allowedHttpHookUrls`
+      logForDebugging(msg, { level: 'warn' })
+      return { ok: false, body: '', error: msg }
+    }
+  }
+
+  const timeoutMs = hook.timeout
+    ? hook.timeout * 1000
+    : DEFAULT_HTTP_HOOK_TIMEOUT_MS
+
+  const { signal: combinedSignal, cleanup } = createCombinedAbortSignal(
+    signal,
+    { timeoutMs },
+  )
+
+  try {
+    // Build headers with env var interpolation in values
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    }
+    if (hook.headers) {
+      // Intersect hook's allowedEnvVars with policy allowlist when policy is set
+      const hookVars = hook.allowedEnvVars ?? []
+      const effectiveVars =
+        policy.allowedEnvVars !== undefined
+          ? hookVars.filter(v => policy.allowedEnvVars!.includes(v))
+          : hookVars
+      const allowedEnvVars = new Set(effectiveVars)
+      for (const [name, value] of Object.entries(hook.headers)) {
+        headers[name] = interpolateEnvVars(value, allowedEnvVars)
+      }
+    }
+
+    // Route through sandbox network proxy when available. The proxy enforces
+    // the domain allowlist and returns 403 for blocked domains.
+    const sandboxProxy = await getSandboxProxyConfig()
+
+    // Detect env var proxy (HTTP_PROXY / HTTPS_PROXY, respecting NO_PROXY).
+    // When set, configureGlobalAgents() has already installed a request
+    // interceptor that sets httpsAgent to an HttpsProxyAgent — the proxy
+    // handles DNS for the target. Skip the SSRF guard in that case, same
+    // as we do for the sandbox proxy, so that we don't accidentally block
+    // a corporate proxy sitting on a private IP (e.g. 10.0.0.1:3128).
+    const envProxyActive =
+      !sandboxProxy &&
+      getProxyUrl() !== undefined &&
+      !shouldBypassProxy(hook.url)
+
+    if (sandboxProxy) {
+      logForDebugging(
+        `Hooks: HTTP hook POST to ${hook.url} (via sandbox proxy :${sandboxProxy.port})`,
+      )
+    } else if (envProxyActive) {
+      logForDebugging(
+        `Hooks: HTTP hook POST to ${hook.url} (via env-var proxy)`,
+      )
+    } else {
+      logForDebugging(`Hooks: HTTP hook POST to ${hook.url}`)
+    }
+
+    const response = await axios.post<string>(hook.url, jsonInput, {
+      headers,
+      signal: combinedSignal,
+      responseType: 'text',
+      validateStatus: () => true,
+      maxRedirects: 0,
+      // Explicit false prevents axios's own env-var proxy detection; when an
+      // env-var proxy is configured, the global axios interceptor installed
+      // by configureGlobalAgents() handles it via httpsAgent instead.
+      proxy: sandboxProxy ?? false,
+      // SSRF guard: validate resolved IPs, block private/link-local ranges
+      // (but allow loopback for local dev). Skipped when any proxy is in
+      // use — the proxy performs DNS for the target, and applying the
+      // guard would instead validate the proxy's own IP, breaking
+      // connections to corporate proxies on private networks.
+      lookup: sandboxProxy || envProxyActive ? undefined : ssrfGuardedLookup,
+    })
+
+    cleanup()
+
+    const body = response.data ?? ''
+    logForDebugging(
+      `Hooks: HTTP hook response status ${response.status}, body length ${body.length}`,
+    )
+
+    return {
+      ok: response.status >= 200 && response.status < 300,
+      statusCode: response.status,
+      body,
+    }
+  } catch (error) {
+    cleanup()
+
+    if (combinedSignal.aborted) {
+      return { ok: false, body: '', aborted: true }
+    }
+
+    const errorMsg = errorMessage(error)
+    logForDebugging(`Hooks: HTTP hook error: ${errorMsg}`, { level: 'error' })
+    return { ok: false, body: '', error: errorMsg }
+  }
+}