state-management

State Management

The pattern

Shared mutable state is wrapped in a deep-immutable type. Direct mutation is a compile error. All updates go through a single setter that accepts a pure function (prev: State) => State. Returning the same reference signals "nothing changed" and skips downstream work — no re-render, no diff.

The reducer function is atomic: the entire state object is replaced in one operation. Partial updates are expressed as spreads — the fields that didn't change carry forward from prev; only the changed fields are new values. This makes every transition explicit, traceable, and race-condition-safe.

Why this matters

Claude Code's AppState is a large object — UI flags, permission context, task records, session configuration — shared across tools running concurrently, React components rendering in a terminal, and background task workers. Without an immutability contract, a tool updating tasks could race with a UI component reading toolPermissionContext mid-update, producing torn reads.

The DeepImmutable<T> wrapper makes that impossible at the type level. TypeScript rejects direct assignment to any nested field. The only way to change state is through the reducer, which replaces the entire object atomically. The reference-equality short-circuit (return prev when nothing changed) prevents the scheduler from scheduling re-renders for no-op updates — important when multiple tasks call setAppState in rapid succession.

How to apply it

1. Read state via context.getAppState() — this returns the current immutable snapshot.
2. Write state via context.setAppState(prev => next). Always return a new object; never mutate prev.
3. For nested updates (e.g. a field inside tasks), spread at every level: { ...prev, tasks: { ...prev.tasks, [id]: updated } }.
4. When the update is conditional and the condition is false, return prev unchanged — this is the reference-equality no-op signal.
5. For repeated nested updates to the same sub-object, extract a helper that handles the spread and the no-op check — if the updater returns the same reference, return prev unchanged to avoid triggering subscribers unnecessarily.
6. Never access state from module-level variables. State always comes from context.getAppState().