@xortex/xcode 3.0.0

package/utils/sessionStart.ts

@@ -0,0 +1,232 @@
+import { getMainThreadAgentType } from '../bootstrap/state.js'
+import type { HookResultMessage } from '../types/message.js'
+import { createAttachmentMessage } from './attachments.js'
+import { logForDebugging } from './debug.js'
+import { withDiagnosticsTiming } from './diagLogs.js'
+import { isBareMode } from './envUtils.js'
+import { updateWatchPaths } from './hooks/fileChangedWatcher.js'
+import { shouldAllowManagedHooksOnly } from './hooks/hooksConfigSnapshot.js'
+import { executeSessionStartHooks, executeSetupHooks } from './hooks.js'
+import { logError } from './log.js'
+import { loadPluginHooks } from './plugins/loadPluginHooks.js'
+
+type SessionStartHooksOptions = {
+  sessionId?: string
+  agentType?: string
+  model?: string
+  forceSyncExecution?: boolean
+}
+
+// Set by processSessionStartHooks when a hook emits initialUserMessage;
+// consumed once by takeInitialUserMessage. This side channel avoids changing
+// the Promise<HookResultMessage[]> return type that main.tsx and print.ts
+// both already await on (sessionStartHooksPromise is kicked in main.tsx and
+// joined later — rippling a structural return-type change through that
+// handoff would touch five callsites for what is a print-mode-only value).
+let pendingInitialUserMessage: string | undefined
+
+export function takeInitialUserMessage(): string | undefined {
+  const v = pendingInitialUserMessage
+  pendingInitialUserMessage = undefined
+  return v
+}
+
+// Note to CLAUDE: do not add ANY "warmup" logic. It is **CRITICAL** that you do not add extra work on startup.
+export async function processSessionStartHooks(
+  source: 'startup' | 'resume' | 'clear' | 'compact',
+  {
+    sessionId,
+    agentType,
+    model,
+    forceSyncExecution,
+  }: SessionStartHooksOptions = {},
+): Promise<HookResultMessage[]> {
+  // --bare skips all hooks. executeHooks already early-returns under --bare
+  // (hooks.ts:1861), but this skips the loadPluginHooks() await below too —
+  // no point loading plugin hooks that'll never run.
+  if (isBareMode()) {
+    return []
+  }
+  const hookMessages: HookResultMessage[] = []
+  const additionalContexts: string[] = []
+  const allWatchPaths: string[] = []
+
+  // Skip loading plugin hooks if restricted to managed hooks only
+  // Plugin hooks are untrusted external code that should be blocked by policy
+  if (shouldAllowManagedHooksOnly()) {
+    logForDebugging('Skipping plugin hooks - allowManagedHooksOnly is enabled')
+  } else {
+    // Ensure plugin hooks are loaded before executing SessionStart hooks.
+    // loadPluginHooks() may be called early during startup (fire-and-forget, non-blocking)
+    // to pre-load hooks, but we must guarantee hooks are registered before executing them.
+    // This function is memoized, so if hooks are already loaded, this returns immediately
+    // with negligible overhead (just a cache lookup).
+    try {
+      await withDiagnosticsTiming('load_plugin_hooks', () => loadPluginHooks())
+    } catch (error) {
+      // Log error but don't crash - continue with session start without plugin hooks
+      /* eslint-disable no-restricted-syntax -- both branches wrap with context, not a toError case */
+      const enhancedError =
+        error instanceof Error
+          ? new Error(
+              `Failed to load plugin hooks during ${source}: ${error.message}`,
+            )
+          : new Error(
+              `Failed to load plugin hooks during ${source}: ${String(error)}`,
+            )
+      /* eslint-enable no-restricted-syntax */
+
+      if (error instanceof Error && error.stack) {
+        enhancedError.stack = error.stack
+      }
+
+      logError(enhancedError)
+
+      // Provide specific guidance based on error type
+      const errorMessage =
+        error instanceof Error ? error.message : String(error)
+      let userGuidance = ''
+
+      if (
+        errorMessage.includes('Failed to clone') ||
+        errorMessage.includes('network') ||
+        errorMessage.includes('ETIMEDOUT') ||
+        errorMessage.includes('ENOTFOUND')
+      ) {
+        userGuidance =
+          'This appears to be a network issue. Check your internet connection and try again.'
+      } else if (
+        errorMessage.includes('Permission denied') ||
+        errorMessage.includes('EACCES') ||
+        errorMessage.includes('EPERM')
+      ) {
+        userGuidance =
+          'This appears to be a permissions issue. Check file permissions on ~/.claude/plugins/'
+      } else if (
+        errorMessage.includes('Invalid') ||
+        errorMessage.includes('parse') ||
+        errorMessage.includes('JSON') ||
+        errorMessage.includes('schema')
+      ) {
+        userGuidance =
+          'This appears to be a configuration issue. Check your plugin settings in .claude/settings.json'
+      } else {
+        userGuidance =
+          'Please fix the plugin configuration or remove problematic plugins from your settings.'
+      }
+
+      logForDebugging(
+        `Warning: Failed to load plugin hooks. SessionStart hooks from plugins will not execute. ` +
+          `Error: ${errorMessage}. ${userGuidance}`,
+        { level: 'warn' },
+      )
+
+      // Continue execution - plugin hooks won't be available, but project-level hooks
+      // from .claude/settings.json (loaded via captureHooksConfigSnapshot) will still work
+    }
+  }
+
+  // Execute SessionStart hooks, ignoring blocking errors
+  // Use the provided agentType or fall back to the one stored in bootstrap state
+  const resolvedAgentType = agentType ?? getMainThreadAgentType()
+  for await (const hookResult of executeSessionStartHooks(
+    source,
+    sessionId,
+    resolvedAgentType,
+    model,
+    undefined,
+    undefined,
+    forceSyncExecution,
+  )) {
+    if (hookResult.message) {
+      hookMessages.push(hookResult.message)
+    }
+    if (
+      hookResult.additionalContexts &&
+      hookResult.additionalContexts.length > 0
+    ) {
+      additionalContexts.push(...hookResult.additionalContexts)
+    }
+    if (hookResult.initialUserMessage) {
+      pendingInitialUserMessage = hookResult.initialUserMessage
+    }
+    if (hookResult.watchPaths && hookResult.watchPaths.length > 0) {
+      allWatchPaths.push(...hookResult.watchPaths)
+    }
+  }
+
+  if (allWatchPaths.length > 0) {
+    updateWatchPaths(allWatchPaths)
+  }
+
+  // If hooks provided additional context, add it as a message
+  if (additionalContexts.length > 0) {
+    const contextMessage = createAttachmentMessage({
+      type: 'hook_additional_context',
+      content: additionalContexts,
+      hookName: 'SessionStart',
+      toolUseID: 'SessionStart',
+      hookEvent: 'SessionStart',
+    })
+    hookMessages.push(contextMessage)
+  }
+
+  return hookMessages
+}
+
+export async function processSetupHooks(
+  trigger: 'init' | 'maintenance',
+  { forceSyncExecution }: { forceSyncExecution?: boolean } = {},
+): Promise<HookResultMessage[]> {
+  // Same rationale as processSessionStartHooks above.
+  if (isBareMode()) {
+    return []
+  }
+  const hookMessages: HookResultMessage[] = []
+  const additionalContexts: string[] = []
+
+  if (shouldAllowManagedHooksOnly()) {
+    logForDebugging('Skipping plugin hooks - allowManagedHooksOnly is enabled')
+  } else {
+    try {
+      await loadPluginHooks()
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error)
+      logForDebugging(
+        `Warning: Failed to load plugin hooks. Setup hooks from plugins will not execute. Error: ${errorMessage}`,
+        { level: 'warn' },
+      )
+    }
+  }
+
+  for await (const hookResult of executeSetupHooks(
+    trigger,
+    undefined,
+    undefined,
+    forceSyncExecution,
+  )) {
+    if (hookResult.message) {
+      hookMessages.push(hookResult.message)
+    }
+    if (
+      hookResult.additionalContexts &&
+      hookResult.additionalContexts.length > 0
+    ) {
+      additionalContexts.push(...hookResult.additionalContexts)
+    }
+  }
+
+  if (additionalContexts.length > 0) {
+    const contextMessage = createAttachmentMessage({
+      type: 'hook_additional_context',
+      content: additionalContexts,
+      hookName: 'Setup',
+      toolUseID: 'Setup',
+      hookEvent: 'Setup',
+    })
+    hookMessages.push(contextMessage)
+  }
+
+  return hookMessages
+}

package/utils/sessionState.ts

@@ -0,0 +1,150 @@
+export type SessionState = 'idle' | 'running' | 'requires_action'
+
+/**
+ * Context carried with requires_action transitions so downstream
+ * surfaces (CCR sidebar, push notifications) can show what the
+ * session is blocked on, not just that it's blocked.
+ *
+ * Two delivery paths:
+ * - tool_name + action_description → RequiresActionDetails proto
+ *   (webhook payload, typed, logged in Datadog)
+ * - full object → external_metadata.pending_action (queryable JSON
+ *   on the Session, lets the frontend iterate on shape without
+ *   proto round-trips)
+ */
+export type RequiresActionDetails = {
+  tool_name: string
+  /** Human-readable summary, e.g. "Editing src/foo.ts", "Running npm test" */
+  action_description: string
+  tool_use_id: string
+  request_id: string
+  /** Raw tool input — the frontend reads from external_metadata.pending_action.input
+   * to parse question options / plan content without scanning the event stream. */
+  input?: Record<string, unknown>
+}
+
+import { isEnvTruthy } from './envUtils.js'
+import type { PermissionMode } from './permissions/PermissionMode.js'
+import { enqueueSdkEvent } from './sdkEventQueue.js'
+
+// CCR external_metadata keys — push in onChangeAppState, restore in
+// externalMetadataToAppState.
+export type SessionExternalMetadata = {
+  permission_mode?: string | null
+  is_ultraplan_mode?: boolean | null
+  model?: string | null
+  pending_action?: RequiresActionDetails | null
+  // Opaque — typed at the emit site. Importing PostTurnSummaryOutput here
+  // would leak the import path string into sdk.d.ts via agentSdkBridge's
+  // re-export of SessionState.
+  post_turn_summary?: unknown
+  // Mid-turn progress line from the forked-agent summarizer — fires every
+  // ~5 steps / 2min so long-running turns still surface "what's happening
+  // right now" before post_turn_summary arrives.
+  task_summary?: string | null
+}
+
+type SessionStateChangedListener = (
+  state: SessionState,
+  details?: RequiresActionDetails,
+) => void
+type SessionMetadataChangedListener = (
+  metadata: SessionExternalMetadata,
+) => void
+type PermissionModeChangedListener = (mode: PermissionMode) => void
+
+let stateListener: SessionStateChangedListener | null = null
+let metadataListener: SessionMetadataChangedListener | null = null
+let permissionModeListener: PermissionModeChangedListener | null = null
+
+export function setSessionStateChangedListener(
+  cb: SessionStateChangedListener | null,
+): void {
+  stateListener = cb
+}
+
+export function setSessionMetadataChangedListener(
+  cb: SessionMetadataChangedListener | null,
+): void {
+  metadataListener = cb
+}
+
+/**
+ * Register a listener for permission-mode changes from onChangeAppState.
+ * Wired by print.ts to emit an SDK system:status message so CCR/IDE clients
+ * see mode transitions in real time — regardless of which code path mutated
+ * toolPermissionContext.mode (Shift+Tab, ExitPlanMode dialog, slash command,
+ * bridge set_permission_mode, etc.).
+ */
+export function setPermissionModeChangedListener(
+  cb: PermissionModeChangedListener | null,
+): void {
+  permissionModeListener = cb
+}
+
+let hasPendingAction = false
+let currentState: SessionState = 'idle'
+
+export function getSessionState(): SessionState {
+  return currentState
+}
+
+export function notifySessionStateChanged(
+  state: SessionState,
+  details?: RequiresActionDetails,
+): void {
+  currentState = state
+  stateListener?.(state, details)
+
+  // Mirror details into external_metadata so GetSession carries the
+  // pending-action context without proto changes. Cleared via RFC 7396
+  // null on the next non-blocked transition.
+  if (state === 'requires_action' && details) {
+    hasPendingAction = true
+    metadataListener?.({
+      pending_action: details,
+    })
+  } else if (hasPendingAction) {
+    hasPendingAction = false
+    metadataListener?.({ pending_action: null })
+  }
+
+  // task_summary is written mid-turn by the forked summarizer; clear it at
+  // idle so the next turn doesn't briefly show the previous turn's progress.
+  if (state === 'idle') {
+    metadataListener?.({ task_summary: null })
+  }
+
+  // Mirror to the SDK event stream so non-CCR consumers (scmuxd, VS Code)
+  // see the same authoritative idle/running signal the CCR bridge does.
+  // 'idle' fires after heldBackResult flushes — lets scmuxd flip IDLE and
+  // show the bg-task dot instead of a stuck generating spinner.
+  //
+  // Opt-in until CCR web + mobile clients learn to ignore this subtype in
+  // their isWorking() last-message heuristics — the trailing idle event
+  // currently pins them at "Running...".
+  // https://anthropic.slack.com/archives/C093BJBD1CP/p1774152406752229
+  if (isEnvTruthy(process.env.CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS)) {
+    enqueueSdkEvent({
+      type: 'system',
+      subtype: 'session_state_changed',
+      state,
+    })
+  }
+}
+
+export function notifySessionMetadataChanged(
+  metadata: SessionExternalMetadata,
+): void {
+  metadataListener?.(metadata)
+}
+
+/**
+ * Fired by onChangeAppState when toolPermissionContext.mode changes.
+ * Downstream listeners (CCR external_metadata PUT, SDK status stream) are
+ * both wired through this single choke point so no mode-mutation path can
+ * silently bypass them.
+ */
+export function notifyPermissionModeChanged(mode: PermissionMode): void {
+  permissionModeListener?.(mode)
+}