状态管理

大多数 React 应用程序在其状态需要跨越组件树时都会使用库（Redux、Zustand、Jotai）。 Claude Code 用 35 行 TypeScript 从头开始​​构建自己的存储，并将其直接插入到 React 的内置中 useSyncExternalStore 钩。 了解原因以及最重要的内容对于应对 REPL 的任何重要更改至关重要。

该架构具有三个不同的层：

整个商店原语位于 state/store.ts。 三个概念，35行：

type Listener = () => void
type OnChange<T> = (args: { newState: T; oldState: T }) => void

export type Store<T> = {
  getState: () => T
  setState: (updater: (prev: T) => T) => void
  subscribe: (listener: Listener) => () => void
}

export function createStore<T>(
  initialState: T,
  onChange?: OnChange<T>,
): Store<T> {
  let state = initialState
  const listeners = new Set<Listener>()

  return {
    getState: () => state,

    setState: (updater) => {
      const prev = state
      const next = updater(prev)
      if (Object.is(next, prev)) return   // bail if no change
      state = next
      onChange?.({ newState: next, oldState: prev })  // side-effect hook
      for (const listener of listeners) listener()  // notify React
    },

    subscribe: (listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)  // unsubscribe
    },
  }
}

为什么不使用useState/useReducer？

React 自己的钩子将状态生命周期与组件树联系起来。 Claude Code 需要可从非 React 代码读取的状态：无头模式、SDK 打印层、每个进程的队友会话、 onChangeAppState 副作用链。 一个普通的 JS 对象，带有 Set 的侦听器在 React 之外传递不需要任何成本。

为什么不声明/Jotai？

零额外的捆绑依赖。 接口 Claude Code 实际上需要 — getState, setState, subscribe — 准确映射到什么 useSyncExternalStore 需要。 没有什么可买的了。

// From AppState.tsx — the full useAppState implementation:
export function useAppState(selector) {
  const store = useAppStore()
  const get = () => selector(store.getState())
  return useSyncExternalStore(store.subscribe, get, get)
}

AppState 定义于 state/AppStateStore.ts。 它很大——超过 90 个不同的领域——但它有清晰的内部结构。 类型是 DeepImmutable<{...}> 对于可序列化部分，有少量字段可以转义不变性包装器（函数类型、 Map, Set）明确列在 &.

这些字段分为六个逻辑类别：

选定的字段参考

export type AppState = DeepImmutable<{
  settings: SettingsJson
  verbose: boolean
  // ... ~60 serializable fields ...
}> & {
  // Excluded from DeepImmutable — contain function types
  tasks: { [taskId: string]: TaskState }
  agentNameRegistry: Map<string, AgentId>
  mcp: { clients: MCPServerConnection[]; /* ... */ }
  // ...
}

type SpeculationState =
  | { status: 'idle' }
  | {
      status: 'active'
      id: string
      abort: () => void
      startTime: number
      messagesRef: { current: Message[] }     // mutable ref — no array copy per msg
      writtenPathsRef: { current: Set<string> } // relative paths in overlay
      boundary: CompletionBoundary | null
      suggestionLength: number
      toolUseCount: number
      isPipelined: boolean
      contextRef: { current: REPLHookContext }
      pipelinedSuggestion?: { text: string; promptId: ...; generationRequestId: ... } | null
    }

第二个参数 createStore 是一个可选的 onChange 打回来。 Claude Code 通过 onChangeAppState 这里 - 触发的单个函数 every 状态转换和差异相关字段以驱动副作用。

当前的 diff 块位于 onChangeAppState:

export function onChangeAppState({ newState, oldState }) {

  // 1. Permission mode — sync to CCR external_metadata + SDK status stream
  const prevMode = oldState.toolPermissionContext.mode
  const newMode = newState.toolPermissionContext.mode
  if (prevMode !== newMode) {
    const prevExternal = toExternalPermissionMode(prevMode)
    const newExternal  = toExternalPermissionMode(newMode)
    if (prevExternal !== newExternal) {
      // Guard: internal-only modes (bubble, ungated-auto) don't pollute CCR.
      // is_ultraplan_mode set null per RFC 7396 (removes key from JSON patch).
      notifySessionMetadataChanged({ permission_mode: newExternal, ... })
    }
    notifyPermissionModeChanged(newMode)  // SDK channel — passes raw mode
  }

  // 2. mainLoopModel — persist to settings + bootstrap override
  if (newState.mainLoopModel !== oldState.mainLoopModel) {
    if (newState.mainLoopModel === null) {
      updateSettingsForSource('userSettings', { model: undefined })
      setMainLoopModelOverride(null)
    } else {
      updateSettingsForSource('userSettings', { model: newState.mainLoopModel })
      setMainLoopModelOverride(newState.mainLoopModel)
    }
  }

  // 3. expandedView — persist to globalConfig (showExpandedTodos / showSpinnerTree)
  if (newState.expandedView !== oldState.expandedView) {
    saveGlobalConfig(current => ({
      ...current,
      showExpandedTodos: newState.expandedView === 'tasks',
      showSpinnerTree:   newState.expandedView === 'teammates',
    }))
  }

  // 4. verbose — persist to globalConfig
  if (newState.verbose !== oldState.verbose) {
    saveGlobalConfig(current => ({ ...current, verbose: newState.verbose }))
  }

  // 5. tungstenPanelVisible — ant-only, persist to globalConfig
  if (process.env.USER_TYPE === 'ant' && newState.tungstenPanelVisible !== oldState.tungstenPanelVisible) {
    saveGlobalConfig(current => ({ ...current, tungstenPanelVisible: newState.tungstenPanelVisible }))
  }

  // 6. settings — clear auth caches + re-apply env vars
  if (newState.settings !== oldState.settings) {
    clearApiKeyHelperCache()
    clearAwsCredentialsCache()
    clearGcpCredentialsCache()
    if (newState.settings.env !== oldState.settings.env) {
      applyConfigEnvironmentVariables()
    }
  }
}

外化守卫

并非所有内部权限模式都有外部等效模式。 这 toExternalPermissionMode 调用折叠了仅限内部的名称，例如 'bubble' and 'ungated-auto' to 'default' 在发送至 CCR 之前。 如果没有这个，远程仪表板将收到无意义的模式名称，并可能在内部转换上循环（default → bubble → default）从外部是看不见的。

export function externalMetadataToAppState(
  metadata: SessionExternalMetadata
): (prev: AppState) => AppState {
  return prev => ({
    ...prev,
    ...(typeof metadata.permission_mode === 'string'
      ? { toolPermissionContext: {
            ...prev.toolPermissionContext,
            mode: permissionModeFromString(metadata.permission_mode),
          }}
      : {}),
    ...(typeof metadata.is_ultraplan_mode === 'boolean'
      ? { isUltraplanMode: metadata.is_ultraplan_mode }
      : {}),
  })
}

state/AppState.tsx 是商店的 React 面孔。 它导出三个钩子和一个提供程序。 该文件是 React 编译的（带有 _c 来自 React 编译器），所以原始源代码读起来有点奇怪——但语义很干净。

// Read a slice — re-renders only when the selected value changes
const verbose = useAppState(s => s.verbose)
const model   = useAppState(s => s.mainLoopModel)

// Write without subscribing — stable reference, never causes re-renders
const setAppState = useSetAppState()
setAppState(prev => ({ ...prev, verbose: true }))

// Get the raw store — for passing to non-React helpers
const store = useAppStateStore()
doSomethingOutsideReact(store.getState, store.setState)

// Good — returns existing reference
const { text, promptId } = useAppState(s => s.promptSuggestion)

// Bad — new object every render
const { text, promptId } = useAppState(s => ({ text: s.promptSuggestion.text, promptId: s.promptSuggestion.promptId }))

AppStateProvider 设置

AppStateProvider 创建商店一次（通过 useState 惰性初始化器），电线 onChangeAppState 如果在安装组件之前加载了远程设置，则应用一次性修复：

const [store] = useState(() =>
  createStore(
    initialState ?? getDefaultAppState(),
    onChangeAppState,        // side-effect hook wired here
  )
)

// One-time remote-settings fixup on mount
useEffect(() => {
  const { toolPermissionContext } = store.getState()
  if (toolPermissionContext.isBypassPermissionsModeAvailable
      && isBypassPermissionsModeDisabled()) {
    store.setState(prev => ({
      ...prev,
      toolPermissionContext: createDisabledBypassPermissionsContext(prev.toolPermissionContext)
    }))
  }
}, [])

selectors.ts — 纯派生

state/selectors.ts 包含从中导出计算值的函数 AppState 切片而不访问商店或产生副作用。 他们接受一个 Pick<AppState, ...> （不是完整状态），以便调用者可以单独测试它们。

/**
 * Get the currently viewed teammate task, if any.
 * Takes a Pick — not the full AppState — so tests don't need the whole object.
 */
export function getViewedTeammateTask(
  appState: Pick<AppState, 'viewingAgentTaskId' | 'tasks'>
): InProcessTeammateTaskState | undefined { ... }

/**
 * Discriminated union — tells input routing exactly where to send a message.
 */
export type ActiveAgentForInput =
  | { type: 'leader' }
  | { type: 'viewed';     task: InProcessTeammateTaskState }
  | { type: 'named_agent'; task: LocalAgentTaskState       }

export function getActiveAgentForInput(appState: AppState): ActiveAgentForInput { ... }

teammateViewHelpers.ts — 共置状态转换

队友视图功能的状态转换更加复杂 state/teammateViewHelpers.ts。 这些不是 React hooks——它们需要 setAppState 作为一个参数，使它们可以在任何上下文中进行测试和使用。

// Enter a teammate's transcript view — retain: true blocks eviction, loads from disk
export function enterTeammateView(
  taskId: string,
  setAppState: (updater: (prev: AppState) => AppState) => void,
): void

// Exit back to leader's view — releases retain, schedules eviction if terminal
export function exitTeammateView(
  setAppState: (updater: (prev: AppState) => AppState) => void,
): void

// Context-sensitive x button: abort if running, dismiss if terminal
export function stopOrDismissAgent(
  taskId: string,
  setAppState: (updater: (prev: AppState) => AppState) => void,
): void

状态更新如何从组件通过系统移动：

并非所有内容都在 context/ 是传统意义上的React Context。 该目录包含多种模式：