Architecture: How should AI agents determine which session they are workin...

Documentation for Sessions

🏗️ Architecture: How should AI agents determine which session they are workin...

Date: 2026-03-27
Time: 14:28:02 UTC
Session: gspace2-0
Agent: storage
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should AI agents determine which session they are working on, given that the current system relies on agents remembering session numbers (which they frequently forget)?

Task: Smart Session System v13.0 — eliminate agent session misassignment

🎯 Decision Made

Chosen:

Git-context-first resolution: a 5-step cascade that derives session identity from branch name and commit tags, never falling back to history.json activeSessions for the session NUMBER. The cascade: 1) explicit param, 2) simple branch session-{N}, 3) range branch + recent commit tags, 4) manifest gitBranch cross-reference, 5) new session creation with max+1.

Options Considered:

  1. A) Pure MCP-layer resolution only — no hooks or git enforcement
  2. B) MCP resolution + git hooks + Claude Code hook upgrade (CHOSEN)
  3. C) Conservative approach — keep current behavior but add more warnings
  4. D) Aggressive approach — MCP tools refuse to work without explicit session

💭 Reasoning

Root cause: agents don't reliably pass sessionNumber to preflight(). The system then guesses from history.json activeSessions, which has 5+ concurrent entries and frequently returns the wrong session. SubSessions work well because they're auto-incremented — the agent doesn't choose them. Applying the same principle: what the system can infer, the agent should never have to remember. Git context (branch name + commit tags [S{N}.{sub}]) is the most reliable signal because it represents actual work done. The branch IS the session identity. history.json is demoted from 'source of truth' to 'sub-session tracking cache'. This eliminates the entire class of wrong-session bugs without requiring any agent behavior change.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation