状态管理：AppState 与 React Context 体系

Claude Code 的状态管理架构基于 React Context + 外部 Store 模式，通过不可变状态树与订阅机制实现高效的状态更新与组件渲染优化。该系统承担了从用户交互、工具执行、权限管理到远程会话协调的全局状态维护职责，是整个 CLI 应用的神经中枢。

核心架构：三层分离设计

状态管理系统采用 类型定义 / Store 实现 / React 集成 的三层分离架构，这种设计使得类型系统、状态逻辑与 UI 层可以独立演进，同时保持了高度的测试性和可维护性。

graph TB
    subgraph "React 集成层"
        ASP[AppStateProvider]
        UAS[useAppState Hook]
        USA[useSetAppState Hook]
        UASM[useAppStateMaybeOutsideOfProvider]
    end
    
    subgraph "Store 实现层"
        CS[createStore]
        GS[getState]
        SS[setState]
        SUB[subscribe]
    end
    
    subgraph "类型定义层"
        AST[AppState Type]
        DAS[getDefaultAppState]
        AS[AppStateStore Type]
    end
    
    ASP --> CS
    CS --> AST
    CS --> AS
    UAS --> SUB
    UAS --> GS
    USA --> SS
    UASM --> SUB
    UASM --> GS
    
    style ASP fill:#e1f5ff
    style CS fill:#fff4e1
    style AST fill:#f0f0f0

类型定义层 (src/state/AppStateStore.ts) 包含 570 行的状态类型声明，定义了 AppState 接口的所有字段及其不可变性约束（通过 DeepImmutable 包装），以及 getDefaultAppState() 工厂函数用于初始化状态树。Store 实现层 (src/state/store.ts) 提供了极简的响应式 Store 实现（仅 35 行），包含 getState()、setState() 和 subscribe() 三个核心方法，基于 Object.is 比较实现变更检测。React 集成层 (src/state/AppState.tsx) 通过 AppStateProvider 组件将 Store 实例注入 React Context，并提供 useAppState()、useSetAppState() 等 hooks 供组件消费状态。

Sources: AppStateStore.ts store.ts AppState.tsx

AppState 状态树结构

AppState 类型定义了应用的全局状态结构，包含 基础配置、任务管理、MCP 集成、插件系统、团队协作、通知系统 等核心领域。状态树采用不可变设计，所有更新通过 setState(updater) 函数以纯函数方式完成。

基础配置与运行时状态

type AppState = DeepImmutable<{
  // 用户配置
  settings: SettingsJson
  verbose: boolean
  mainLoopModel: ModelSetting
  mainLoopModelForSession: ModelSetting
  
  // 运行时状态
  statusLineText: string | undefined
  expandedView: 'none' | 'tasks' | 'teammates'
  isBriefOnly: boolean
  footerSelection: FooterItem | null
  spinnerTip?: string
  
  // 权限与模式
  toolPermissionContext: ToolPermissionContext
  agent: string | undefined
  kairosEnabled: boolean
  
  // 远程会话
  remoteSessionUrl: string | undefined
  remoteConnectionStatus: 'connecting' | 'connected' | 'reconnecting' | 'disconnected'
  remoteBackgroundTaskCount: number
  
  // Bridge 系统
  replBridgeEnabled: boolean
  replBridgeConnected: boolean
  replBridgeSessionActive: boolean
  replBridgeConnectUrl: string | undefined
  // ... 更多 Bridge 状态
}>

基础配置字段（如 verbose、mainLoopModel）直接映射 CLI 参数和用户设置，运行时状态字段（如 statusLineText、expandedView）控制 UI 展示行为。权限管理通过 toolPermissionContext 集中维护，包含当前权限模式（default/plan/auto/yolo 等）和工具权限规则。

Sources: AppStateStore.ts

任务与代理状态管理

任务系统采用 统一任务注册表 设计，所有异步任务（包括本地主会话、子代理、远程代理、后台 Shell）都存储在 tasks 字典中，通过 TaskState 类型区分任务类型和状态。

{
  tasks: { [taskId: string]: TaskState }
  agentNameRegistry: Map<string, AgentId>
  foregroundedTaskId?: string
  viewingAgentTaskId?: string
}

agentNameRegistry 维护代理名称到 AgentId 的映射，用于 SendMessageTool 的名称路由。foregroundedTaskId 标识当前前台任务的 ID，其消息会显示在主视图中；viewingAgentTaskId 用于队友模式下的消息预览，允许用户查看子代理的对话历史而不切换前台任务。

Sources: AppStateStore.ts

MCP 与插件系统状态

MCP (Model Context Protocol) 集成通过 mcp 字段管理服务器连接、工具、命令和资源，通过 pluginReconnectKey 实现插件热重载的响应式更新。

{
  mcp: {
    clients: MCPServerConnection[]
    tools: Tool[]
    commands: Command[]
    resources: Record<string, ServerResource[]>
    pluginReconnectKey: number
  },
  plugins: {
    enabled: LoadedPlugin[]
    disabled: LoadedPlugin[]
    commands: Command[]
    errors: PluginError[]
    installationStatus: {
      marketplaces: Array<{...}>
      plugins: Array<{...}>
    }
    needsRefresh: boolean
  }
}

插件系统独立维护 enabled/disabled 列表、加载错误、安装状态和刷新标记。needsRefresh 字段在后台插件变更（如市场安装、外部设置编辑）时设置为 true，触发用户执行 /reload-plugins 命令刷新插件状态。

Sources: AppStateStore.ts

团队协作与通知系统

团队协作状态通过 teamContext 维护，包含团队名称、文件路径、领导者 ID、队友信息和 swarm 成员身份。通知系统采用 优先级队列 设计，支持文本和 JSX 两种通知类型，通过 invalidates 字段实现通知互斥。

{
  teamContext?: {
    teamName: string
    teamFilePath: string
    leadAgentId: string
    selfAgentId?: string
    selfAgentName?: string
    isLeader?: boolean
    teammates: {
      [teammateId: string]: {
        name: string
        agentType?: string
        color?: string
        tmuxSessionName: string
        tmuxPaneId: string
        cwd: string
        worktreePath?: string
        spawnedAt: number
      }
    }
  },
  notifications: {
    current: Notification | null
    queue: Notification[]
  }
}

Sources: AppStateStore.ts AppStateStore.ts

特殊领域状态

系统还包含多个特殊领域的状态字段：推测执行 (speculation/speculationSessionTimeSavedMs)、技能改进建议 (skillImprovement)、权限请求队列 (workerSandboxPermissions/pendingWorkerRequest)、Tmux 集成 (tungstenActiveSession/tungstenPanelVisible)、计算机使用 MCP (computerUseMcpState)、REPL 上下文 (replContext)、收件箱轮询 (inbox) 等。这些字段通过类型系统确保类型安全，并通过不可变约束防止意外修改。

Sources: AppStateStore.ts

Store 实现与订阅机制

createStore<T> 函数实现了一个 极简响应式 Store，核心逻辑仅 35 行代码，却提供了完整的状态管理和订阅功能。

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

  return {
    getState: () => state,
    
    setState: (updater: (prev: T) => T) => {
      const prev = state
      const next = updater(prev)
      if (Object.is(next, prev)) return  // 变更检测
      state = next
      onChange?.({ newState: next, oldState: prev })  // 全局监听器
      for (const listener of listeners) listener()    // 订阅者通知
    },
    
    subscribe: (listener: Listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)  // 返回取消订阅函数
    },
  }
}

关键设计点包括：变更检测 使用 Object.is 比较新旧状态，避免不必要的重新渲染；全局监听器 (onChange) 在每次状态变更后调用，用于副作用处理（如持久化、遥测）；订阅者通知 遍历所有监听器，触发 React 组件的 useSyncExternalStore 更新。

Sources: store.ts

React 集成：Context Provider 与 Hooks

AppStateProvider 组件负责创建 Store 实例并将其注入 React Context 树，同时包装 MailboxProvider 和 VoiceProvider 等子 Context。

export function AppStateProvider({
  children,
  initialState,
  onChangeAppState,
}: Props) {
  const [store] = useState(() => 
    createStore(initialState ?? getDefaultAppState(), onChangeAppState)
  )
  
  useEffect(() => {
    // 初始化时检查并禁用绕过权限模式
    const { toolPermissionContext } = store.getState()
    if (toolPermissionContext.isBypassPermissionsModeAvailable && 
        isBypassPermissionsModeDisabled()) {
      store.setState(prev => ({
        ...prev,
        toolPermissionContext: createDisabledBypassPermissionsContext(prev.toolPermissionContext)
      }))
    }
  }, [])
  
  // 监听设置变更
  useSettingsChange(source => applySettingsChange(source, store.setState))
  
  return (
    <HasAppStateContext.Provider value={true}>
      <AppStoreContext.Provider value={store}>
        <MailboxProvider>
          <VoiceProvider>{children}</VoiceProvider>
        </MailboxProvider>
      </AppStoreContext.Provider>
    </HasAppStateContext.Provider>
  )
}

Provider 组件使用 useState 确保 Store 实例在组件生命周期内保持稳定，通过 HasAppStateContext 防止嵌套 Provider，并在挂载时执行权限模式检查。useSettingsChange hook 监听用户设置变更，自动将设置更新同步到 AppState。

Sources: AppState.tsx

状态订阅 Hook：useAppState

useAppState<T>(selector: (state: AppState) => T) 是组件消费状态的核心 Hook，基于 useSyncExternalStore 实现精准的订阅和渲染优化。

export function useAppState<T>(selector: (state: AppState) => T): T {
  const store = useAppStore()
  
  const getSnapshot = useCallback(() => {
    const state = store.getState()
    const selected = selector(state)
    return selected
  }, [selector, store])
  
  return useSyncExternalStore(store.subscribe, getSnapshot, getSnapshot)
}

关键优化策略包括：选择器模式 要求调用者传入 selector 函数，只订阅所需的状态切片，避免不必要的重新渲染；稳定引用 通过 useCallback 缓存 getSnapshot 函数，防止每次渲染创建新函数；Object.is 比较 由 useSyncExternalStore 自动处理，只有当 selector 返回值变化时才触发重新渲染。

最佳实践：对于多个独立字段，应多次调用 Hook 而非返回对象：

// ✅ 推荐：独立订阅，精准更新
const verbose = useAppState(s => s.verbose)
const model = useAppState(s => s.mainLoopModel)

// ❌ 避免：返回新对象，每次渲染都变化
const { verbose, model } = useAppState(s => ({ 
  verbose: s.verbose, 
  model: s.mainLoopModel 
}))

Sources: AppState.tsx

状态更新 Hook：useSetAppState

useSetAppState() 返回 Store 的 setState 函数，用于更新状态而不订阅任何状态变化。由于 setState 引用稳定，使用此 Hook 的组件不会因状态变化而重新渲染。

export function useSetAppState() {
  return useAppStore().setState
}

典型用法是在事件处理器或副作用中更新状态：

const setAppState = useSetAppState()

const handleToggle = useCallback(() => {
  setAppState(prev => ({
    ...prev,
    expandedView: prev.expandedView === 'tasks' ? 'none' : 'tasks'
  }))
}, [setAppState])

Sources: AppState.tsx

安全访问 Hook：useAppStateMaybeOutsideOfProvider

某些组件可能在 AppStateProvider 外部渲染（如对话框、错误边界），此时使用 useAppStateMaybeOutsideOfProvider 可以安全访问状态，返回 undefined 而非抛出错误。

export function useAppStateMaybeOutsideOfProvider<T>(
  selector: (state: AppState) => T
): T | undefined {
  const store = useContext(AppStoreContext)
  
  const getSnapshot = useCallback(
    () => store ? selector(store.getState()) : undefined,
    [selector, store]
  )
  
  return useSyncExternalStore(
    store ? store.subscribe : NOOP_SUBSCRIBE,
    getSnapshot
  )
}

Sources: AppState.tsx

状态变更副作用：onChangeAppState

onChangeAppState 函数作为 Store 的全局监听器，在每次状态变更后执行副作用，包括 权限模式同步、设置持久化、缓存清理 等。这种设计将副作用逻辑集中管理，避免了在多个 setAppState 调用点散布副作用代码。

export function onChangeAppState({
  newState,
  oldState,
}: {
  newState: AppState
  oldState: AppState
}) {
  // 权限模式变更 → 通知 CCR 和 SDK
  const prevMode = oldState.toolPermissionContext.mode
  const newMode = newState.toolPermissionContext.mode
  if (prevMode !== newMode) {
    const prevExternal = toExternalPermissionMode(prevMode)
    const newExternal = toExternalPermissionMode(newMode)
    if (prevExternal !== newExternal) {
      notifySessionMetadataChanged({
        permission_mode: newExternal,
        is_ultraplan_mode: /* ... */
      })
    }
    notifyPermissionModeChanged(newMode)
  }
  
  // 模型变更 → 持久化到设置
  if (newState.mainLoopModel !== oldState.mainLoopModel) {
    if (newState.mainLoopModel === null) {
      updateSettingsForSource('userSettings', { model: undefined })
    } else {
      updateSettingsForSource('userSettings', { model: newState.mainLoopModel })
    }
  }
  
  // expandedView 变更 → 持久化到全局配置
  if (newState.expandedView !== oldState.expandedView) {
    saveGlobalConfig(current => ({
      ...current,
      showExpandedTodos: newState.expandedView === 'tasks',
      showSpinnerTree: newState.expandedView === 'teammates',
    }))
  }
  
  // 设置变更 → 清理认证缓存
  if (newState.settings !== oldState.settings) {
    clearApiKeyHelperCache()
    clearAwsCredentialsCache()
    clearGcpCredentialsCache()
    if (newState.settings.env !== oldState.settings.env) {
      applyConfigEnvironmentVariables()
    }
  }
}

核心副作用包括：权限模式同步 将内部权限模式转换为外部格式后通知 CCR (Claude Code Remote) 和 SDK；模型持久化 将 mainLoopModel 变更同步到用户设置文件；UI 状态持久化 将 expandedView 映射到 showExpandedTodos/showSpinnerTree 并保存到全局配置；缓存失效 在设置变更时清理认证相关缓存，确保新设置立即生效。

Sources: onChangeAppState.ts

选择器模式：派生状态计算

选择器函数用于从 AppState 中计算派生状态，保持逻辑集中和可测试性。selectors.ts 提供了两个核心选择器：getViewedTeammateTask 和 getActiveAgentForInput。

export function getViewedTeammateTask(
  appState: Pick<AppState, 'viewingAgentTaskId' | 'tasks'>
): InProcessTeammateTaskState | undefined {
  const { viewingAgentTaskId, tasks } = appState
  
  if (!viewingAgentTaskId) return undefined
  
  const task = tasks[viewingAgentTaskId]
  if (!task || !isInProcessTeammateTask(task)) return undefined
  
  return task
}

export function getActiveAgentForInput(
  appState: AppState
): ActiveAgentForInput {
  const viewedTask = getViewedTeammateTask(appState)
  if (viewedTask) {
    return { type: 'viewed', task: viewedTask }
  }
  
  const { viewingAgentTaskId, tasks } = appState
  if (viewingAgentTaskId) {
    const task = tasks[viewingAgentTaskId]
    if (task?.type === 'local_agent') {
      return { type: 'named_agent', task }
    }
  }
  
  return { type: 'leader' }
}

getActiveAgentForInput 返回 判别联合类型，用于类型安全的输入路由：当用户查看队友时返回 { type: 'viewed', task }，当查看命名代理时返回 { type: 'named_agent', task }，否则返回 { type: 'leader' }。这种设计避免了运行时类型检查，通过 TypeScript 类型系统保证类型安全。

Sources: selectors.ts

Context Provider 层次结构

AppStateProvider 在 React 组件树中的位置决定了其与其他 Context Provider 的集成方式。在 App.tsx 中，AppStateProvider 包装了整个应用，内部嵌套 StatsProvider 和 FpsMetricsProvider。

export function App({
  getFpsMetrics,
  stats,
  initialState,
  children
}: Props) {
  return (
    <AppStateProvider 
      initialState={initialState} 
      onChangeAppState={onChangeAppState}
    >
      <StatsProvider store={stats}>
        <FpsMetricsProvider getFpsMetrics={getFpsMetrics}>
          {children}
        </FpsMetricsProvider>
      </StatsProvider>
    </AppStateProvider>
  )
}

AppStateProvider 内部还包装了 MailboxProvider（用于团队消息传递）和 VoiceProvider（用于语音模式），形成完整的 Context 层次结构。StatsProvider 提供统计信息上下文，FpsMetricsProvider 提供 FPS 性能指标上下文。

Sources: App.tsx AppState.tsx

辅助 Context Provider

除了核心的 AppStateProvider，系统还包含多个辅助 Context Provider 用于特定领域的状态管理：

MailboxProvider (src/context/mailbox.tsx) 提供团队协作的邮箱机制，用于代理间消息传递。它创建一个 Mailbox 实例并通过 Context 传递给子组件：

export function MailboxProvider({ children }: Props) {
  const mailbox = useMemo(() => new Mailbox(), [])
  return (
    <MailboxContext.Provider value={mailbox}>
      {children}
    </MailboxContext.Provider>
  )
}

NotificationsProvider 通过 useNotifications Hook 提供通知队列管理，内部使用 useAppStateStore 和 useSetAppState 操作 AppState 的 notifications 字段。通知系统支持 优先级队列、超时自动移除、立即显示 (immediate priority) 和 通知合并 (fold 函数) 等特性。

Sources: mailbox.tsx notifications.tsx

实际应用：REPL 组件的状态集成

REPL.tsx 作为主屏幕组件，展示了如何在实际场景中使用状态管理系统。它通过多个 useAppState 调用订阅不同的状态切片，并通过 useSetAppState 更新状态。

export function REPL({ ... }: Props) {
  // 订阅多个状态切片
  const expandedView = useAppState(s => s.expandedView)
  const isBriefOnly = useAppState(s => s.isBriefOnly)
  const toolPermissionContext = useAppState(s => s.toolPermissionContext)
  const foregroundedTaskId = useAppState(s => s.foregroundedTaskId)
  const remoteConnectionStatus = useAppState(s => s.remoteConnectionStatus)
  const replBridgeConnected = useAppState(s => s.replBridgeConnected)
  
  // 获取状态更新函数（不触发重新渲染）
  const setAppState = useSetAppState()
  
  // 使用选择器获取派生状态
  const viewedTeammateTask = getViewedTeammateTask(
    useAppState(s => ({ 
      viewingAgentTaskId: s.viewingAgentTaskId, 
      tasks: s.tasks 
    }))
  )
  
  // 在事件处理器中更新状态
  const handleToggleExpandedView = useCallback(() => {
    setAppState(prev => ({
      ...prev,
      expandedView: prev.expandedView === 'tasks' ? 'none' : 'tasks'
    }))
  }, [setAppState])
  
  // ...
}

REPL 组件还使用了 GlobalKeybindingHandlers 组件，该组件内部也通过 useAppState 和 useSetAppState 实现全局快捷键的状态管理：

export function GlobalKeybindingHandlers({ ... }: Props): null {
  const expandedView = useAppState(s => s.expandedView)
  const setAppState = useSetAppState()
  
  const handleToggleTodos = useCallback(() => {
    setAppState(prev => {
      const hasTeammates = count(
        getAllInProcessTeammateTasks(prev.tasks), 
        t => t.status === 'running'
      ) > 0
      
      if (hasTeammates) {
        // 循环切换：none → tasks → teammates → none
        switch (prev.expandedView) {
          case 'none': return { ...prev, expandedView: 'tasks' }
          case 'tasks': return { ...prev, expandedView: 'teammates' }
          case 'teammates': return { ...prev, expandedView: 'none' }
        }
      }
      // 二元切换：none ↔ tasks
      return { 
        ...prev, 
        expandedView: prev.expandedView === 'tasks' ? 'none' : 'tasks' 
      }
    })
  }, [expandedView, setAppState])
  
  // ...
}

Sources: REPL.tsx useGlobalKeybindings.tsx

性能优化策略

状态管理系统的性能优化策略集中在 减少不必要的重新渲染 和 避免对象引用变化 两个方面。

选择器优化

使用 useAppState 时，应避免返回新对象或数组，因为这会导致 Object.is 比较失败，触发不必要的重新渲染：

// ❌ 错误：每次调用都创建新对象
const { verbose, model } = useAppState(s => ({ 
  verbose: s.verbose, 
  model: s.mainLoopModel 
}))

// ✅ 正确：分别订阅原始值
const verbose = useAppState(s => s.verbose)
const model = useAppState(s => s.mainLoopModel)

// ✅ 正确：订阅已存在的子对象
const { text, promptId } = useAppState(s => s.promptSuggestion)

Sources: AppState.tsx

状态更新优化

setState 函数通过 Object.is 比较新旧状态，如果状态未实际变化（如返回了相同的对象引用），则跳过监听器通知：

setState: (updater: (prev: T) => T) => {
  const prev = state
  const next = updater(prev)
  if (Object.is(next, prev)) return  // 跳过未变更的更新
  state = next
  onChange?.({ newState: next, oldState: prev })
  for (const listener of listeners) listener()
}

这要求更新逻辑正确使用不可变模式：

// ✅ 正确：创建新对象
setAppState(prev => ({ ...prev, verbose: !prev.verbose }))

// ❌ 错误：修改原对象（违反不可变性）
setAppState(prev => {
  prev.verbose = !prev.verbose  // 不要这样做！
  return prev
})

Sources: store.ts

Context 分离

通过将不同领域的状态分离到独立的 Context Provider（如 MailboxProvider、StatsProvider、FpsMetricsProvider），可以避免 AppState 变化导致所有消费者重新渲染。例如，MailboxProvider 的值是一个稳定的 Mailbox 实例，不会因 AppState 变化而改变，因此只有直接订阅 mailbox 的组件才会重新渲染。

Sources: mailbox.tsx App.tsx

与其他系统的集成

Bootstrap State (全局单例状态)

src/bootstrap/state.ts 维护了应用启动时的全局单例状态（如 sessionId、projectRoot、modelUsage 等），这些状态与 AppState 相互独立但存在交互。例如，setMainLoopModelOverride 函数在 onChangeAppState 中被调用，用于同步 AppState 的 mainLoopModel 到 bootstrap state：

if (newState.mainLoopModel !== oldState.mainLoopModel) {
  if (newState.mainLoopModel === null) {
    updateSettingsForSource('userSettings', { model: undefined })
    setMainLoopModelOverride(null)  // 同步到 bootstrap state
  } else {
    updateSettingsForSource('userSettings', { model: newState.mainLoopModel })
    setMainLoopModelOverride(newState.mainLoopModel)
  }
}

这种设计允许非 React 代码（如工具实现、API 客户端）通过 bootstrap state 访问关键信息，而 React 组件通过 AppState 订阅响应式更新。

Sources: bootstrap/state.ts onChangeAppState.ts

Context 系统 (src/context.ts)

src/context.ts 提供了 系统上下文 和 用户上下文 的构建逻辑，这些上下文在查询时作为系统提示注入到对话中。虽然与 AppState 分离，但某些上下文数据（如 claudeMd 内容）会被缓存到 bootstrap state，供 AppState 的 promptSuggestion 系统使用。

export const getUserContext = memoize(async () => {
  const claudeMd = shouldDisableClaudeMd
    ? null
    : getClaudeMds(filterInjectedMemoryFiles(await getMemoryFiles()))
  
  setCachedClaudeMdContent(claudeMd || null)  // 缓存到 bootstrap state
  
  return {
    ...(claudeMd && { claudeMd }),
    currentDate: `Today's date is ${getLocalISODate()}.`,
  }
})

Sources: context.ts

初始化与默认状态

getDefaultAppState() 函数负责构建初始状态树，所有字段都设置为合理的默认值。该函数在 AppStateProvider 中被调用，当未提供 initialState 参数时使用：

export function getDefaultAppState(): AppState {
  const initialMode: PermissionMode =
    teammateUtils.isTeammate() && teammateUtils.isPlanModeRequired()
      ? 'plan'
      : 'default'

  return {
    settings: getInitialSettings(),
    tasks: {},
    agentNameRegistry: new Map(),
    verbose: false,
    mainLoopModel: null,
    mainLoopModelForSession: null,
    statusLineText: undefined,
    expandedView: 'none',
    isBriefOnly: false,
    showTeammateMessagePreview: false,
    selectedIPAgentIndex: -1,
    coordinatorTaskIndex: -1,
    viewSelectionMode: 'none',
    footerSelection: null,
    kairosEnabled: false,
    remoteSessionUrl: undefined,
    remoteConnectionStatus: 'connecting',
    remoteBackgroundTaskCount: 0,
    replBridgeEnabled: false,
    // ... 所有其他字段的默认值
    toolPermissionContext: {
      ...getEmptyToolPermissionContext(),
      mode: initialMode,
    },
    // ...
  }
}

对于队友模式下的会话，初始权限模式会被设置为 'plan'，否则为 'default'。所有集合类型字段（如 Map、Set）都初始化为空实例，避免 undefined 检查的复杂性。

Sources: AppStateStore.ts

架构优势与设计原则

Claude Code 的状态管理系统体现了以下架构优势：

类型安全与不可变性：通过 DeepImmutable<AppState> 类型包装，TypeScript 编译器会在编译时捕获所有尝试直接修改状态的代码。这确保了所有状态更新都通过 setState 函数进行，便于追踪和调试。

精准订阅与渲染优化：基于 useSyncExternalStore 的选择器模式允许组件只订阅所需的状态切片，结合 Object.is 比较机制，最小化重新渲染范围。在包含数百个组件的大型应用中，这种优化至关重要。

集中式副作用管理：通过 onChangeAppState 全局监听器，所有状态变更的副作用（如持久化、通知、缓存清理）都集中在一个地方，避免了在多个调用点散布副作用代码，提高了可维护性和可测试性。

渐进式复杂度：简单的组件只需调用 useAppState(s => s.field) 即可订阅状态，复杂的组件可以使用 useSetAppState 进行状态更新，高级用户可以直接访问 Store 实例（通过 useAppStateStore）进行非 React 代码集成。这种渐进式复杂度设计使得系统既易于使用，又具备足够的灵活性。

测试友好：由于状态逻辑与 UI 完全分离，可以独立测试 Store 实现、选择器函数和副作用函数，无需渲染 React 组件。createStore 函数可以在测试中直接调用，传入自定义的初始状态和 onChange 监听器。

与 React 18+ 并发特性兼容：基于 useSyncExternalStore 的实现确保了与 React 并发模式（Concurrent Mode）的兼容性，支持时间切片和优先级调度等特性。

本页介绍了 Claude Code 的核心状态管理系统，包括 AppState 结构、Store 实现、React 集成、选择器模式、副作用管理和性能优化策略。下一页 查询引擎：QueryEngine 对话生命周期管理 将深入探讨如何使用 AppState 中的消息和工具状态来驱动 AI 对话流程。