@xortex/xcode 3.0.0

package/utils/hooks/hooksSettings.ts

@@ -0,0 +1,271 @@
+import { resolve } from 'path'
+import type { HookEvent } from 'src/entrypoints/agentSdkTypes.js'
+import { getSessionId } from '../../bootstrap/state.js'
+import type { AppState } from '../../state/AppState.js'
+import type { EditableSettingSource } from '../settings/constants.js'
+import { SOURCES } from '../settings/constants.js'
+import {
+  getSettingsFilePathForSource,
+  getSettingsForSource,
+} from '../settings/settings.js'
+import type { HookCommand, HookMatcher } from '../settings/types.js'
+import { DEFAULT_HOOK_SHELL } from '../shell/shellProvider.js'
+import { getSessionHooks } from './sessionHooks.js'
+
+export type HookSource =
+  | EditableSettingSource
+  | 'policySettings'
+  | 'pluginHook'
+  | 'sessionHook'
+  | 'builtinHook'
+
+export interface IndividualHookConfig {
+  event: HookEvent
+  config: HookCommand
+  matcher?: string
+  source: HookSource
+  pluginName?: string
+}
+
+/**
+ * Check if two hooks are equal (comparing only command/prompt content, not timeout)
+ */
+export function isHookEqual(
+  a: HookCommand | { type: 'function'; timeout?: number },
+  b: HookCommand | { type: 'function'; timeout?: number },
+): boolean {
+  if (a.type !== b.type) return false
+
+  // Use switch for exhaustive type checking
+  // Note: We only compare command/prompt content, not timeout
+  // `if` is part of identity: same command with different `if` conditions
+  // are distinct hooks (e.g., setup.sh if=Bash(git *) vs if=Bash(npm *)).
+  const sameIf = (x: { if?: string }, y: { if?: string }) =>
+    (x.if ?? '') === (y.if ?? '')
+  switch (a.type) {
+    case 'command':
+      // shell is part of identity: same command string with different
+      // shells are distinct hooks. Default 'bash' so undefined === 'bash'.
+      return (
+        b.type === 'command' &&
+        a.command === b.command &&
+        (a.shell ?? DEFAULT_HOOK_SHELL) === (b.shell ?? DEFAULT_HOOK_SHELL) &&
+        sameIf(a, b)
+      )
+    case 'prompt':
+      return b.type === 'prompt' && a.prompt === b.prompt && sameIf(a, b)
+    case 'agent':
+      return b.type === 'agent' && a.prompt === b.prompt && sameIf(a, b)
+    case 'http':
+      return b.type === 'http' && a.url === b.url && sameIf(a, b)
+    case 'function':
+      // Function hooks can't be compared (no stable identifier)
+      return false
+  }
+}
+
+/** Get the display text for a hook */
+export function getHookDisplayText(
+  hook: HookCommand | { type: 'callback' | 'function'; statusMessage?: string },
+): string {
+  // Return custom status message if provided
+  if ('statusMessage' in hook && hook.statusMessage) {
+    return hook.statusMessage
+  }
+
+  switch (hook.type) {
+    case 'command':
+      return hook.command
+    case 'prompt':
+      return hook.prompt
+    case 'agent':
+      return hook.prompt
+    case 'http':
+      return hook.url
+    case 'callback':
+      return 'callback'
+    case 'function':
+      return 'function'
+  }
+}
+
+export function getAllHooks(appState: AppState): IndividualHookConfig[] {
+  const hooks: IndividualHookConfig[] = []
+
+  // Check if restricted to managed hooks only
+  const policySettings = getSettingsForSource('policySettings')
+  const restrictedToManagedOnly = policySettings?.allowManagedHooksOnly === true
+
+  // If allowManagedHooksOnly is set, don't show any hooks in the UI
+  // (user/project/local are blocked, and managed hooks are intentionally hidden)
+  if (!restrictedToManagedOnly) {
+    // Get hooks from all editable sources
+    const sources = [
+      'userSettings',
+      'projectSettings',
+      'localSettings',
+    ] as EditableSettingSource[]
+
+    // Track which settings files we've already processed to avoid duplicates
+    // (e.g., when running from home directory, userSettings and projectSettings
+    // both resolve to ~/.claude/settings.json)
+    const seenFiles = new Set<string>()
+
+    for (const source of sources) {
+      const filePath = getSettingsFilePathForSource(source)
+      if (filePath) {
+        const resolvedPath = resolve(filePath)
+        if (seenFiles.has(resolvedPath)) {
+          continue
+        }
+        seenFiles.add(resolvedPath)
+      }
+
+      const sourceSettings = getSettingsForSource(source)
+      if (!sourceSettings?.hooks) {
+        continue
+      }
+
+      for (const [event, matchers] of Object.entries(sourceSettings.hooks)) {
+        for (const matcher of matchers as HookMatcher[]) {
+          for (const hookCommand of matcher.hooks) {
+            hooks.push({
+              event: event as HookEvent,
+              config: hookCommand,
+              matcher: matcher.matcher,
+              source,
+            })
+          }
+        }
+      }
+    }
+  }
+
+  // Get session hooks
+  const sessionId = getSessionId()
+  const sessionHooks = getSessionHooks(appState, sessionId)
+  for (const [event, matchers] of sessionHooks.entries()) {
+    for (const matcher of matchers) {
+      for (const hookCommand of matcher.hooks) {
+        hooks.push({
+          event,
+          config: hookCommand,
+          matcher: matcher.matcher,
+          source: 'sessionHook',
+        })
+      }
+    }
+  }
+
+  return hooks
+}
+
+export function getHooksForEvent(
+  appState: AppState,
+  event: HookEvent,
+): IndividualHookConfig[] {
+  return getAllHooks(appState).filter(hook => hook.event === event)
+}
+
+export function hookSourceDescriptionDisplayString(source: HookSource): string {
+  switch (source) {
+    case 'userSettings':
+      return 'User settings (~/.claude/settings.json)'
+    case 'projectSettings':
+      return 'Project settings (.claude/settings.json)'
+    case 'localSettings':
+      return 'Local settings (.claude/settings.local.json)'
+    case 'pluginHook':
+      // TODO: Get the actual plugin hook file paths instead of using glob pattern
+      // We should capture the specific plugin paths during hook registration and display them here
+      // e.g., "Plugin hooks (~/.claude/plugins/repos/source/example-plugin/example-plugin/hooks/hooks.json)"
+      return 'Plugin hooks (~/.claude/plugins/*/hooks/hooks.json)'
+    case 'sessionHook':
+      return 'Session hooks (in-memory, temporary)'
+    case 'builtinHook':
+      return 'Built-in hooks (registered internally by Claude Code)'
+    default:
+      return source as string
+  }
+}
+
+export function hookSourceHeaderDisplayString(source: HookSource): string {
+  switch (source) {
+    case 'userSettings':
+      return 'User Settings'
+    case 'projectSettings':
+      return 'Project Settings'
+    case 'localSettings':
+      return 'Local Settings'
+    case 'pluginHook':
+      return 'Plugin Hooks'
+    case 'sessionHook':
+      return 'Session Hooks'
+    case 'builtinHook':
+      return 'Built-in Hooks'
+    default:
+      return source as string
+  }
+}
+
+export function hookSourceInlineDisplayString(source: HookSource): string {
+  switch (source) {
+    case 'userSettings':
+      return 'User'
+    case 'projectSettings':
+      return 'Project'
+    case 'localSettings':
+      return 'Local'
+    case 'pluginHook':
+      return 'Plugin'
+    case 'sessionHook':
+      return 'Session'
+    case 'builtinHook':
+      return 'Built-in'
+    default:
+      return source as string
+  }
+}
+
+export function sortMatchersByPriority(
+  matchers: string[],
+  hooksByEventAndMatcher: Record<
+    string,
+    Record<string, IndividualHookConfig[]>
+  >,
+  selectedEvent: HookEvent,
+): string[] {
+  // Create a priority map based on SOURCES order (lower index = higher priority)
+  const sourcePriority = SOURCES.reduce(
+    (acc, source, index) => {
+      acc[source] = index
+      return acc
+    },
+    {} as Record<EditableSettingSource, number>,
+  )
+
+  return [...matchers].sort((a, b) => {
+    const aHooks = hooksByEventAndMatcher[selectedEvent]?.[a] || []
+    const bHooks = hooksByEventAndMatcher[selectedEvent]?.[b] || []
+
+    const aSources = Array.from(new Set(aHooks.map(h => h.source)))
+    const bSources = Array.from(new Set(bHooks.map(h => h.source)))
+
+    // Sort by highest priority source first (lowest priority number)
+    // Plugin hooks get lowest priority (highest number)
+    const getSourcePriority = (source: HookSource) =>
+      source === 'pluginHook' || source === 'builtinHook'
+        ? 999
+        : sourcePriority[source as EditableSettingSource]
+
+    const aHighestPriority = Math.min(...aSources.map(getSourcePriority))
+    const bHighestPriority = Math.min(...bSources.map(getSourcePriority))
+
+    if (aHighestPriority !== bHighestPriority) {
+      return aHighestPriority - bHighestPriority
+    }
+
+    // If same priority, sort by matcher name
+    return a.localeCompare(b)
+  })
+}

package/utils/hooks/postSamplingHooks.ts

@@ -0,0 +1,70 @@
+import type { QuerySource } from '../../constants/querySource.js'
+import type { ToolUseContext } from '../../Tool.js'
+import type { Message } from '../../types/message.js'
+import { toError } from '../errors.js'
+import { logError } from '../log.js'
+import type { SystemPrompt } from '../systemPromptType.js'
+
+// Post-sampling hook - not exposed in settings.json config (yet), only used programmatically
+
+// Generic context for REPL hooks (both post-sampling and stop hooks)
+export type REPLHookContext = {
+  messages: Message[] // Full message history including assistant responses
+  systemPrompt: SystemPrompt
+  userContext: { [k: string]: string }
+  systemContext: { [k: string]: string }
+  toolUseContext: ToolUseContext
+  querySource?: QuerySource
+}
+
+export type PostSamplingHook = (
+  context: REPLHookContext,
+) => Promise<void> | void
+
+// Internal registry for post-sampling hooks
+const postSamplingHooks: PostSamplingHook[] = []
+
+/**
+ * Register a post-sampling hook that will be called after model sampling completes
+ * This is an internal API not exposed through settings
+ */
+export function registerPostSamplingHook(hook: PostSamplingHook): void {
+  postSamplingHooks.push(hook)
+}
+
+/**
+ * Clear all registered post-sampling hooks (for testing)
+ */
+export function clearPostSamplingHooks(): void {
+  postSamplingHooks.length = 0
+}
+
+/**
+ * Execute all registered post-sampling hooks
+ */
+export async function executePostSamplingHooks(
+  messages: Message[],
+  systemPrompt: SystemPrompt,
+  userContext: { [k: string]: string },
+  systemContext: { [k: string]: string },
+  toolUseContext: ToolUseContext,
+  querySource?: QuerySource,
+): Promise<void> {
+  const context: REPLHookContext = {
+    messages,
+    systemPrompt,
+    userContext,
+    systemContext,
+    toolUseContext,
+    querySource,
+  }
+
+  for (const hook of postSamplingHooks) {
+    try {
+      await hook(context)
+    } catch (error) {
+      // Log but don't fail on hook errors
+      logError(toError(error))
+    }
+  }
+}

package/utils/hooks/registerFrontmatterHooks.ts

@@ -0,0 +1,67 @@
+import { HOOK_EVENTS, type HookEvent } from 'src/entrypoints/agentSdkTypes.js'
+import type { AppState } from 'src/state/AppState.js'
+import { logForDebugging } from '../debug.js'
+import type { HooksSettings } from '../settings/types.js'
+import { addSessionHook } from './sessionHooks.js'
+
+/**
+ * Register hooks from frontmatter (agent or skill) into session-scoped hooks.
+ * These hooks will be active for the duration of the session/agent and cleaned up
+ * when the session/agent ends.
+ *
+ * @param setAppState Function to update app state
+ * @param sessionId Session ID to scope the hooks (agent ID for agents, session ID for skills)
+ * @param hooks The hooks settings from frontmatter
+ * @param sourceName Human-readable source name for logging (e.g., "agent 'my-agent'")
+ * @param isAgent If true, converts Stop hooks to SubagentStop (since subagents trigger SubagentStop, not Stop)
+ */
+export function registerFrontmatterHooks(
+  setAppState: (updater: (prev: AppState) => AppState) => void,
+  sessionId: string,
+  hooks: HooksSettings,
+  sourceName: string,
+  isAgent: boolean = false,
+): void {
+  if (!hooks || Object.keys(hooks).length === 0) {
+    return
+  }
+
+  let hookCount = 0
+
+  for (const event of HOOK_EVENTS) {
+    const matchers = hooks[event]
+    if (!matchers || matchers.length === 0) {
+      continue
+    }
+
+    // For agents, convert Stop hooks to SubagentStop since that's what fires when an agent completes
+    // (executeStopHooks uses SubagentStop when called with an agentId)
+    let targetEvent: HookEvent = event
+    if (isAgent && event === 'Stop') {
+      targetEvent = 'SubagentStop'
+      logForDebugging(
+        `Converting Stop hook to SubagentStop for ${sourceName} (subagents trigger SubagentStop)`,
+      )
+    }
+
+    for (const matcherConfig of matchers) {
+      const matcher = matcherConfig.matcher ?? ''
+      const hooksArray = matcherConfig.hooks
+
+      if (!hooksArray || hooksArray.length === 0) {
+        continue
+      }
+
+      for (const hook of hooksArray) {
+        addSessionHook(setAppState, sessionId, targetEvent, matcher, hook)
+        hookCount++
+      }
+    }
+  }
+
+  if (hookCount > 0) {
+    logForDebugging(
+      `Registered ${hookCount} frontmatter hook(s) from ${sourceName} for session ${sessionId}`,
+    )
+  }
+}

package/utils/hooks/registerSkillHooks.ts

@@ -0,0 +1,64 @@
+import { HOOK_EVENTS } from 'src/entrypoints/agentSdkTypes.js'
+import type { AppState } from 'src/state/AppState.js'
+import { logForDebugging } from '../debug.js'
+import type { HooksSettings } from '../settings/types.js'
+import { addSessionHook, removeSessionHook } from './sessionHooks.js'
+
+/**
+ * Registers hooks from a skill's frontmatter as session hooks.
+ *
+ * Hooks are registered as session-scoped hooks that persist for the duration
+ * of the session. If a hook has `once: true`, it will be automatically removed
+ * after its first successful execution.
+ *
+ * @param setAppState - Function to update the app state
+ * @param sessionId - The current session ID
+ * @param hooks - The hooks settings from the skill's frontmatter
+ * @param skillName - The name of the skill (for logging)
+ * @param skillRoot - The base directory of the skill (for CLAUDE_PLUGIN_ROOT env var)
+ */
+export function registerSkillHooks(
+  setAppState: (updater: (prev: AppState) => AppState) => void,
+  sessionId: string,
+  hooks: HooksSettings,
+  skillName: string,
+  skillRoot?: string,
+): void {
+  let registeredCount = 0
+
+  for (const eventName of HOOK_EVENTS) {
+    const matchers = hooks[eventName]
+    if (!matchers) continue
+
+    for (const matcher of matchers) {
+      for (const hook of matcher.hooks) {
+        // For once: true hooks, use onHookSuccess callback to remove after execution
+        const onHookSuccess = hook.once
+          ? () => {
+              logForDebugging(
+                `Removing one-shot hook for event ${eventName} in skill '${skillName}'`,
+              )
+              removeSessionHook(setAppState, sessionId, eventName, hook)
+            }
+          : undefined
+
+        addSessionHook(
+          setAppState,
+          sessionId,
+          eventName,
+          matcher.matcher || '',
+          hook,
+          onHookSuccess,
+          skillRoot,
+        )
+        registeredCount++
+      }
+    }
+  }
+
+  if (registeredCount > 0) {
+    logForDebugging(
+      `Registered ${registeredCount} hooks from skill '${skillName}'`,
+    )
+  }
+}