docs: design for session state, compaction, and pluggable permissions

[rdwj]

Summary

Adds planning/session-state-compaction-design.md — the foundation design referenced by #163, #164, #166, #168, and the Phase 0 tracker #182.

These four issues share a contract surface (session row schema, pending-state lifecycle, compaction and permission layering). Without a shared design, we'd re-do the session schema two or three times as each feature discovers what it needs and ship incompatible pause/resume semantics. This doc pins the contract once. Mirrors the precedent set by planning/subagent-tool-design.md.

Notable decisions

• Compaction is client-side. vLLM, llama.cpp, Bedrock, and Vertex do not support server-side compaction (Anthropic's compact_2026_01_12 does, but we target multiple endpoints). Framework owns it.
• Marker-based rolling summary, frozen prefix, pinned tail — matches the dominant production shape across Anthropic, Claude Code, and Codex CLI per the research that informed this design.
• Tool-call/tool-result pairs survive compaction together. Orphaned tool_use_ids are a documented LLM-failure class (LangChain #29637, n8n #7c1985e).
• PermissionSource is pluggable. StaticPermissionSource (yaml) for vanilla RHOAI deployments, KagentiPermissionSource for Kagenti, OGXPermissionSource for LlamaStack-shielded deployments.
• BaseAgent stays unaware of compaction, sessions, and permissions. These remain server-layer ABCs alongside SessionStore and TraceStore.

Phased rollout

• Phase 0 → feat: foundation — stable message IDs, session schema, Compactor + PermissionSource ABCs #182 (this design's implementation: schema, ABCs, stream events)
• Phase 1 → feat: structured Question tool for agent→operator clarification #163 (Question tool)
• Phase 2 → feat: per-tool permission policy (allow | deny | ask) #164 (Permission policy; can land in parallel with Phase 1)
• Phase 3 → feat(server): auto-compaction on context overflow #166 (Auto-compaction)
• Phase 4 → feat(server): session fork and revert at the data layer #168 (Session fork)

Test plan

• Doc renders cleanly in GitHub markdown
• All issue cross-references resolve (feat: structured Question tool for agent→operator clarification #163, feat: per-tool permission policy (allow | deny | ask) #164, feat(server): auto-compaction on context overflow #166, feat(server): session fork and revert at the data layer #168, feat: subagent-as-tool v1 (#165) #173, feat: foundation — stable message IDs, session schema, Compactor + PermissionSource ABCs #182)
• All external links resolve