# State agent guide
## Where to look
| `MissionControlState`, shared models, cache access | `mod.rs` |
| Output events and streaming reconciliation | `output_events.rs` |
| Activity graph, tool/subagent links | `activity_state.rs` |
| Transcript navigation and selection | `transcript_state.rs` |
| Prompt lifecycle and display commands | `prompt_state.rs`, `prompt_actions.rs` |
| Modal selection/input models | `modal.rs` |
| Pane layout and focus | `layout.rs` |
| Agent and provider-context views | `primary_agent_state.rs`, `subagent_viewer.rs`, `provider_context.rs` |
## Local conventions
- `apply_output_event` lives in `output_events.rs`, not the facade. Final assistant/thinking events reconcile text after dropped preview deltas.
- Finish live redaction and control-sanitizer state at hard stream boundaries before appending unrelated rows; otherwise fragments can leak across messages.
- Preserve activity ids used by tree selection, transcript links, and active-tool replacement. Explicit parent relationships take precedence over inferred id ancestry; reject cycles.
- Invalidate affected transcript/activity caches when source rows change. Normalize tool indices, selected rows, and scroll offsets after removals or replacements.
- Keep transcript row metadata inside `TranscriptEntries`. Its append/removal operations prune metadata; state still handles selection and targeted render-cache eviction. Activity ingestion refreshes typed tool and subagent card data.
- Modal previews remain navigation summaries; modal structs hold selection/input affordances, not durable workflow ownership.
- Keep cache/focus/layout state local and reconstruct meaningful display content from normalized final events.
- Extend existing reducer/transition tests in `tests/` or the owning module when behavior changes; no separate test-directory guide.