@xortex/xcode 3.0.0

package/utils/hooks/execPromptHook.ts

@@ -0,0 +1,211 @@
+import { randomUUID } from 'crypto'
+import type { HookEvent } from 'src/entrypoints/agentSdkTypes.js'
+import { queryModelWithoutStreaming } from '../../services/api/gemini.js'
+import type { ToolUseContext } from '../../Tool.js'
+import type { Message } from '../../types/message.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 { safeParseJSON } from '../json.js'
+import { createUserMessage, extractTextContent } from '../messages.js'
+import { getSmallFastModel } from '../model/model.js'
+import type { PromptHook } from '../settings/types.js'
+import { asSystemPrompt } from '../systemPromptType.js'
+import { addArgumentsToPrompt, hookResponseSchema } from './hookHelpers.js'
+
+/**
+ * Execute a prompt-based hook using an LLM
+ */
+export async function execPromptHook(
+  hook: PromptHook,
+  hookName: string,
+  hookEvent: HookEvent,
+  jsonInput: string,
+  signal: AbortSignal,
+  toolUseContext: ToolUseContext,
+  messages?: Message[],
+  toolUseID?: string,
+): Promise<HookResult> {
+  // Use provided toolUseID or generate a new one
+  const effectiveToolUseID = toolUseID || `hook-${randomUUID()}`
+  try {
+    // Replace $ARGUMENTS with the JSON input
+    const processedPrompt = addArgumentsToPrompt(hook.prompt, jsonInput)
+    logForDebugging(
+      `Hooks: Processing prompt 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 })
+
+    // Prepend conversation history if provided
+    const messagesToQuery =
+      messages && messages.length > 0
+        ? [...messages, userMessage]
+        : [userMessage]
+
+    logForDebugging(
+      `Hooks: Querying model with ${messagesToQuery.length} messages`,
+    )
+
+    // Query the model with Haiku
+    const hookTimeoutMs = hook.timeout ? hook.timeout * 1000 : 30000
+
+    // Combined signal: aborts if either the hook signal or timeout triggers
+    const { signal: combinedSignal, cleanup: cleanupSignal } =
+      createCombinedAbortSignal(signal, { timeoutMs: hookTimeoutMs })
+
+    try {
+      const response = await queryModelWithoutStreaming({
+        messages: messagesToQuery,
+        systemPrompt: asSystemPrompt([
+          `You are evaluating a hook in Claude Code.
+
+Your response must be a JSON object matching one of the following schemas:
+1. If the condition is met, return: {"ok": true}
+2. If the condition is not met, return: {"ok": false, "reason": "Reason for why it is not met"}`,
+        ]),
+        thinkingConfig: { type: 'disabled' as const },
+        tools: toolUseContext.options.tools,
+        signal: combinedSignal,
+        options: {
+          async getToolPermissionContext() {
+            const appState = toolUseContext.getAppState()
+            return appState.toolPermissionContext
+          },
+          model: hook.model ?? getSmallFastModel(),
+          toolChoice: undefined,
+          isNonInteractiveSession: true,
+          hasAppendSystemPrompt: false,
+          agents: [],
+          querySource: 'hook_prompt',
+          mcpTools: [],
+          agentId: toolUseContext.agentId,
+          outputFormat: {
+            type: 'json_schema',
+            schema: {
+              type: 'object',
+              properties: {
+                ok: { type: 'boolean' },
+                reason: { type: 'string' },
+              },
+              required: ['ok'],
+              additionalProperties: false,
+            },
+          },
+        },
+      })
+
+      cleanupSignal()
+
+      // Extract text content from response
+      const content = extractTextContent(response.message.content)
+
+      // Update response length for spinner display
+      toolUseContext.setResponseLength(length => length + content.length)
+
+      const fullResponse = content.trim()
+      logForDebugging(`Hooks: Model response: ${fullResponse}`)
+
+      const json = safeParseJSON(fullResponse)
+      if (!json) {
+        logForDebugging(
+          `Hooks: error parsing response as JSON: ${fullResponse}`,
+        )
+        return {
+          hook,
+          outcome: 'non_blocking_error',
+          message: createAttachmentMessage({
+            type: 'hook_non_blocking_error',
+            hookName,
+            toolUseID: effectiveToolUseID,
+            hookEvent,
+            stderr: 'JSON validation failed',
+            stdout: fullResponse,
+            exitCode: 1,
+          }),
+        }
+      }
+
+      const parsed = hookResponseSchema().safeParse(json)
+      if (!parsed.success) {
+        logForDebugging(
+          `Hooks: model response does not conform to expected schema: ${parsed.error.message}`,
+        )
+        return {
+          hook,
+          outcome: 'non_blocking_error',
+          message: createAttachmentMessage({
+            type: 'hook_non_blocking_error',
+            hookName,
+            toolUseID: effectiveToolUseID,
+            hookEvent,
+            stderr: `Schema validation failed: ${parsed.error.message}`,
+            stdout: fullResponse,
+            exitCode: 1,
+          }),
+        }
+      }
+
+      // Failed to meet condition
+      if (!parsed.data.ok) {
+        logForDebugging(
+          `Hooks: Prompt hook condition was not met: ${parsed.data.reason}`,
+        )
+        return {
+          hook,
+          outcome: 'blocking',
+          blockingError: {
+            blockingError: `Prompt hook condition was not met: ${parsed.data.reason}`,
+            command: hook.prompt,
+          },
+          preventContinuation: true,
+          stopReason: parsed.data.reason,
+        }
+      }
+
+      // Condition was met
+      logForDebugging(`Hooks: Prompt hook condition was met`)
+      return {
+        hook,
+        outcome: 'success',
+        message: createAttachmentMessage({
+          type: 'hook_success',
+          hookName,
+          toolUseID: effectiveToolUseID,
+          hookEvent,
+          content: '',
+        }),
+      }
+    } catch (error) {
+      cleanupSignal()
+
+      if (combinedSignal.aborted) {
+        return {
+          hook,
+          outcome: 'cancelled',
+        }
+      }
+      throw error
+    }
+  } catch (error) {
+    const errorMsg = errorMessage(error)
+    logForDebugging(`Hooks: Prompt hook error: ${errorMsg}`)
+    return {
+      hook,
+      outcome: 'non_blocking_error',
+      message: createAttachmentMessage({
+        type: 'hook_non_blocking_error',
+        hookName,
+        toolUseID: effectiveToolUseID,
+        hookEvent,
+        stderr: `Error executing prompt hook: ${errorMsg}`,
+        stdout: '',
+        exitCode: 1,
+      }),
+    }
+  }
+}

package/utils/hooks/fileChangedWatcher.ts

@@ -0,0 +1,191 @@
+import chokidar, { type FSWatcher } from 'chokidar'
+import { isAbsolute, join } from 'path'
+import { registerCleanup } from '../cleanupRegistry.js'
+import { logForDebugging } from '../debug.js'
+import { errorMessage } from '../errors.js'
+import {
+  executeCwdChangedHooks,
+  executeFileChangedHooks,
+  type HookOutsideReplResult,
+} from '../hooks.js'
+import { clearCwdEnvFiles } from '../sessionEnvironment.js'
+import { getHooksConfigFromSnapshot } from './hooksConfigSnapshot.js'
+
+let watcher: FSWatcher | null = null
+let currentCwd: string
+let dynamicWatchPaths: string[] = []
+let dynamicWatchPathsSorted: string[] = []
+let initialized = false
+let hasEnvHooks = false
+let notifyCallback: ((text: string, isError: boolean) => void) | null = null
+
+export function setEnvHookNotifier(
+  cb: ((text: string, isError: boolean) => void) | null,
+): void {
+  notifyCallback = cb
+}
+
+export function initializeFileChangedWatcher(cwd: string): void {
+  if (initialized) return
+  initialized = true
+  currentCwd = cwd
+
+  const config = getHooksConfigFromSnapshot()
+  hasEnvHooks =
+    (config?.CwdChanged?.length ?? 0) > 0 ||
+    (config?.FileChanged?.length ?? 0) > 0
+
+  if (hasEnvHooks) {
+    registerCleanup(async () => dispose())
+  }
+
+  const paths = resolveWatchPaths(config)
+  if (paths.length === 0) return
+
+  startWatching(paths)
+}
+
+function resolveWatchPaths(
+  config?: ReturnType<typeof getHooksConfigFromSnapshot>,
+): string[] {
+  const matchers = (config ?? getHooksConfigFromSnapshot())?.FileChanged ?? []
+
+  // Matcher field: filenames to watch in cwd, pipe-separated (e.g. ".envrc|.env")
+  const staticPaths: string[] = []
+  for (const m of matchers) {
+    if (!m.matcher) continue
+    for (const name of m.matcher.split('|').map(s => s.trim())) {
+      if (!name) continue
+      staticPaths.push(isAbsolute(name) ? name : join(currentCwd, name))
+    }
+  }
+
+  // Combine static matcher paths with dynamic paths from hook output
+  return [...new Set([...staticPaths, ...dynamicWatchPaths])]
+}
+
+function startWatching(paths: string[]): void {
+  logForDebugging(`FileChanged: watching ${paths.length} paths`)
+  watcher = chokidar.watch(paths, {
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 500, pollInterval: 200 },
+    ignorePermissionErrors: true,
+  })
+  watcher.on('change', p => handleFileEvent(p, 'change'))
+  watcher.on('add', p => handleFileEvent(p, 'add'))
+  watcher.on('unlink', p => handleFileEvent(p, 'unlink'))
+}
+
+function handleFileEvent(
+  path: string,
+  event: 'change' | 'add' | 'unlink',
+): void {
+  logForDebugging(`FileChanged: ${event} ${path}`)
+  void executeFileChangedHooks(path, event)
+    .then(({ results, watchPaths, systemMessages }) => {
+      if (watchPaths.length > 0) {
+        updateWatchPaths(watchPaths)
+      }
+      for (const msg of systemMessages) {
+        notifyCallback?.(msg, false)
+      }
+      for (const r of results) {
+        if (!r.succeeded && r.output) {
+          notifyCallback?.(r.output, true)
+        }
+      }
+    })
+    .catch(e => {
+      const msg = errorMessage(e)
+      logForDebugging(`FileChanged hook failed: ${msg}`, {
+        level: 'error',
+      })
+      notifyCallback?.(msg, true)
+    })
+}
+
+export function updateWatchPaths(paths: string[]): void {
+  if (!initialized) return
+  const sorted = paths.slice().sort()
+  if (
+    sorted.length === dynamicWatchPathsSorted.length &&
+    sorted.every((p, i) => p === dynamicWatchPathsSorted[i])
+  ) {
+    return
+  }
+  dynamicWatchPaths = paths
+  dynamicWatchPathsSorted = sorted
+  restartWatching()
+}
+
+function restartWatching(): void {
+  if (watcher) {
+    void watcher.close()
+    watcher = null
+  }
+  const paths = resolveWatchPaths()
+  if (paths.length > 0) {
+    startWatching(paths)
+  }
+}
+
+export async function onCwdChangedForHooks(
+  oldCwd: string,
+  newCwd: string,
+): Promise<void> {
+  if (oldCwd === newCwd) return
+
+  // Re-evaluate from the current snapshot so mid-session hook changes are picked up
+  const config = getHooksConfigFromSnapshot()
+  const currentHasEnvHooks =
+    (config?.CwdChanged?.length ?? 0) > 0 ||
+    (config?.FileChanged?.length ?? 0) > 0
+  if (!currentHasEnvHooks) return
+  currentCwd = newCwd
+
+  await clearCwdEnvFiles()
+  const hookResult = await executeCwdChangedHooks(oldCwd, newCwd).catch(e => {
+    const msg = errorMessage(e)
+    logForDebugging(`CwdChanged hook failed: ${msg}`, {
+      level: 'error',
+    })
+    notifyCallback?.(msg, true)
+    return {
+      results: [] as HookOutsideReplResult[],
+      watchPaths: [] as string[],
+      systemMessages: [] as string[],
+    }
+  })
+  dynamicWatchPaths = hookResult.watchPaths
+  dynamicWatchPathsSorted = hookResult.watchPaths.slice().sort()
+  for (const msg of hookResult.systemMessages) {
+    notifyCallback?.(msg, false)
+  }
+  for (const r of hookResult.results) {
+    if (!r.succeeded && r.output) {
+      notifyCallback?.(r.output, true)
+    }
+  }
+
+  // Re-resolve matcher paths against the new cwd
+  if (initialized) {
+    restartWatching()
+  }
+}
+
+function dispose(): void {
+  if (watcher) {
+    void watcher.close()
+    watcher = null
+  }
+  dynamicWatchPaths = []
+  dynamicWatchPathsSorted = []
+  initialized = false
+  hasEnvHooks = false
+  notifyCallback = null
+}
+
+export function resetFileChangedWatcherForTesting(): void {
+  dispose()
+}

package/utils/hooks/hookEvents.ts

@@ -0,0 +1,192 @@
+/**
+ * Hook event system for broadcasting hook execution events.
+ *
+ * This module provides a generic event system that is separate from the
+ * main message stream. Handlers can register to receive events and decide
+ * what to do with them (e.g., convert to SDK messages, log, etc.).
+ */
+
+import { HOOK_EVENTS } from 'src/entrypoints/sdk/coreTypes.js'
+
+import { logForDebugging } from '../debug.js'
+
+/**
+ * Hook events that are always emitted regardless of the includeHookEvents
+ * option. These are low-noise lifecycle events that were in the original
+ * allowlist and are backwards-compatible.
+ */
+const ALWAYS_EMITTED_HOOK_EVENTS = ['SessionStart', 'Setup'] as const
+
+const MAX_PENDING_EVENTS = 100
+
+export type HookStartedEvent = {
+  type: 'started'
+  hookId: string
+  hookName: string
+  hookEvent: string
+}
+
+export type HookProgressEvent = {
+  type: 'progress'
+  hookId: string
+  hookName: string
+  hookEvent: string
+  stdout: string
+  stderr: string
+  output: string
+}
+
+export type HookResponseEvent = {
+  type: 'response'
+  hookId: string
+  hookName: string
+  hookEvent: string
+  output: string
+  stdout: string
+  stderr: string
+  exitCode?: number
+  outcome: 'success' | 'error' | 'cancelled'
+}
+
+export type HookExecutionEvent =
+  | HookStartedEvent
+  | HookProgressEvent
+  | HookResponseEvent
+export type HookEventHandler = (event: HookExecutionEvent) => void
+
+const pendingEvents: HookExecutionEvent[] = []
+let eventHandler: HookEventHandler | null = null
+let allHookEventsEnabled = false
+
+export function registerHookEventHandler(
+  handler: HookEventHandler | null,
+): void {
+  eventHandler = handler
+  if (handler && pendingEvents.length > 0) {
+    for (const event of pendingEvents.splice(0)) {
+      handler(event)
+    }
+  }
+}
+
+function emit(event: HookExecutionEvent): void {
+  if (eventHandler) {
+    eventHandler(event)
+  } else {
+    pendingEvents.push(event)
+    if (pendingEvents.length > MAX_PENDING_EVENTS) {
+      pendingEvents.shift()
+    }
+  }
+}
+
+function shouldEmit(hookEvent: string): boolean {
+  if ((ALWAYS_EMITTED_HOOK_EVENTS as readonly string[]).includes(hookEvent)) {
+    return true
+  }
+  return (
+    allHookEventsEnabled &&
+    (HOOK_EVENTS as readonly string[]).includes(hookEvent)
+  )
+}
+
+export function emitHookStarted(
+  hookId: string,
+  hookName: string,
+  hookEvent: string,
+): void {
+  if (!shouldEmit(hookEvent)) return
+
+  emit({
+    type: 'started',
+    hookId,
+    hookName,
+    hookEvent,
+  })
+}
+
+export function emitHookProgress(data: {
+  hookId: string
+  hookName: string
+  hookEvent: string
+  stdout: string
+  stderr: string
+  output: string
+}): void {
+  if (!shouldEmit(data.hookEvent)) return
+
+  emit({
+    type: 'progress',
+    ...data,
+  })
+}
+
+export function startHookProgressInterval(params: {
+  hookId: string
+  hookName: string
+  hookEvent: string
+  getOutput: () => Promise<{ stdout: string; stderr: string; output: string }>
+  intervalMs?: number
+}): () => void {
+  if (!shouldEmit(params.hookEvent)) return () => {}
+
+  let lastEmittedOutput = ''
+  const interval = setInterval(() => {
+    void params.getOutput().then(({ stdout, stderr, output }) => {
+      if (output === lastEmittedOutput) return
+      lastEmittedOutput = output
+      emitHookProgress({
+        hookId: params.hookId,
+        hookName: params.hookName,
+        hookEvent: params.hookEvent,
+        stdout,
+        stderr,
+        output,
+      })
+    })
+  }, params.intervalMs ?? 1000)
+  interval.unref()
+
+  return () => clearInterval(interval)
+}
+
+export function emitHookResponse(data: {
+  hookId: string
+  hookName: string
+  hookEvent: string
+  output: string
+  stdout: string
+  stderr: string
+  exitCode?: number
+  outcome: 'success' | 'error' | 'cancelled'
+}): void {
+  // Always log full hook output to debug log for verbose mode debugging
+  const outputToLog = data.stdout || data.stderr || data.output
+  if (outputToLog) {
+    logForDebugging(
+      `Hook ${data.hookName} (${data.hookEvent}) ${data.outcome}:\n${outputToLog}`,
+    )
+  }
+
+  if (!shouldEmit(data.hookEvent)) return
+
+  emit({
+    type: 'response',
+    ...data,
+  })
+}
+
+/**
+ * Enable emission of all hook event types (beyond SessionStart and Setup).
+ * Called when the SDK `includeHookEvents` option is set or when running
+ * in CLAUDE_CODE_REMOTE mode.
+ */
+export function setAllHookEventsEnabled(enabled: boolean): void {
+  allHookEventsEnabled = enabled
+}
+
+export function clearHookEventState(): void {
+  eventHandler = null
+  pendingEvents.length = 0
+  allHookEventsEnabled = false
+}

package/utils/hooks/hookHelpers.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod/v4'
+import type { Tool } from '../../Tool.js'
+import {
+  SYNTHETIC_OUTPUT_TOOL_NAME,
+  SyntheticOutputTool,
+} from '../../tools/SyntheticOutputTool/SyntheticOutputTool.js'
+import { substituteArguments } from '../argumentSubstitution.js'
+import { lazySchema } from '../lazySchema.js'
+import type { SetAppState } from '../messageQueueManager.js'
+import { hasSuccessfulToolCall } from '../messages.js'
+import { addFunctionHook } from './sessionHooks.js'
+
+/**
+ * Schema for hook responses (shared by prompt and agent hooks)
+ */
+export const hookResponseSchema = lazySchema(() =>
+  z.object({
+    ok: z.boolean().describe('Whether the condition was met'),
+    reason: z
+      .string()
+      .describe('Reason, if the condition was not met')
+      .optional(),
+  }),
+)
+
+/**
+ * Add hook input JSON to prompt, either replacing $ARGUMENTS placeholder or appending.
+ * Also supports indexed arguments like $ARGUMENTS[0], $ARGUMENTS[1], or shorthand $0, $1, etc.
+ */
+export function addArgumentsToPrompt(
+  prompt: string,
+  jsonInput: string,
+): string {
+  return substituteArguments(prompt, jsonInput)
+}
+
+/**
+ * Create a StructuredOutput tool configured for hook responses.
+ * Reusable by agent hooks and background verification.
+ */
+export function createStructuredOutputTool(): Tool {
+  return {
+    ...SyntheticOutputTool,
+    inputSchema: hookResponseSchema(),
+    inputJSONSchema: {
+      type: 'object',
+      properties: {
+        ok: {
+          type: 'boolean',
+          description: 'Whether the condition was met',
+        },
+        reason: {
+          type: 'string',
+          description: 'Reason, if the condition was not met',
+        },
+      },
+      required: ['ok'],
+      additionalProperties: false,
+    },
+    async prompt(): Promise<string> {
+      return `Use this tool to return your verification result. You MUST call this tool exactly once at the end of your response.`
+    },
+  }
+}
+
+/**
+ * Register a function hook that enforces structured output via SyntheticOutputTool.
+ * Used by ask.tsx, execAgentHook.ts, and background verification.
+ */
+export function registerStructuredOutputEnforcement(
+  setAppState: SetAppState,
+  sessionId: string,
+): void {
+  addFunctionHook(
+    setAppState,
+    sessionId,
+    'Stop',
+    '', // No matcher - applies to all stops
+    messages => hasSuccessfulToolCall(messages, SYNTHETIC_OUTPUT_TOOL_NAME),
+    `You MUST call the ${SYNTHETIC_OUTPUT_TOOL_NAME} tool to complete this request. Call this tool now.`,
+    { timeout: 5000 },
+  )
+}