F047: Session Context Endpoint

Status: Shipped (v0.11.0) Priority: High Category: Agentic Loop Integration

Problem

Agents starting a new session have no cognitive context. They don’t know:

What decisions were made previously in this domain
What their calibration profile looks like (am I overconfident? in which areas?)
What guardrails are active
What cognitive maintenance is overdue (unreviewed decisions, calibration drift)

Loading this context requires multiple API calls and manual system prompt construction. Most frameworks don’t bother - agents start cold every time.

Solution

A single cstp.getSessionContext endpoint that returns everything an agent needs to be cognitively aware at session start. Designed for injection into system prompts or agent initialization.

API

{
  "method": "cstp.getSessionContext",
  "params": {
    "agent_id": "claude-code",
    "task_description": "Build authentication service for user API",
    "include": ["decisions", "guardrails", "calibration", "ready", "patterns", "contradictions"],
    "decisions_limit": 10,
    "ready_limit": 5,
    "format": "markdown"
  }
}

Response (format: “json”)

{
  "result": {
    "agent_profile": {
      "agent_id": "claude-code",
      "total_decisions": 47,
      "reviewed": 32,
      "overall_accuracy": 0.94,
      "brier_score": 0.028,
      "tendency": "slightly_underconfident",
      "strongest_category": "tooling",
      "weakest_category": "security",
      "active_since": "2026-01-15"
    },

    "relevant_decisions": [
      {
        "id": "dec-7e2f",
        "decision": "Chose JWT for API auth",
        "outcome": "success",
        "date": "2026-01-15",
        "pattern": "Stateless auth scales better",
        "tags": ["auth", "jwt", "architecture"]
      }
    ],

    "active_guardrails": [
      {
        "name": "no-high-stakes-low-confidence",
        "description": "Block if stakes=high and confidence < 0.5",
        "action": "block"
      },
      {
        "name": "no-production-without-review",
        "description": "Require code review for production changes",
        "action": "warn"
      }
    ],

    "calibration_by_category": {
      "architecture": { "accuracy": 0.93, "brier": 0.03, "decisions": 18, "tendency": "well_calibrated" },
      "security": { "accuracy": 0.80, "brier": 0.08, "decisions": 5, "tendency": "overconfident" }
    },

    "ready_queue": [
      {
        "type": "review_outcome",
        "priority": "high",
        "decision_id": "dec-b1c2",
        "reason": "Architecture decision from 12 days ago, no outcome recorded"
      }
    ],

    "confirmed_patterns": [
      { "pattern": "Stateless auth scales better than session-based", "confirmations": 3, "category": "architecture" },
      { "pattern": "Always validate input at API boundary", "confirmations": 5, "category": "security" }
    ],

    "active_contradictions": []
  }
}

Response (format: “markdown”)

When format: "markdown", returns a pre-formatted block ready for system prompt injection:

{
  "result": {
    "markdown": "## CSTP Decision Context\n\n### Your Profile\n- 47 decisions logged, 94% accuracy, Brier 0.028\n- ⚠️ Tendency: slightly underconfident (raise confidence in architecture)\n- ⚠️ Weak area: security (80% accuracy, 5 decisions)\n\n### Relevant Past Decisions\n| Decision | Outcome | Date | Pattern |\n|----------|---------|------|---------|\n| Chose JWT for API auth | ✅ success | 2026-01-15 | Stateless auth scales better |\n...\n\n### Active Guardrails\n- 🚫 no-high-stakes-low-confidence: Block if stakes=high, confidence < 0.5\n- ⚠️ no-production-without-review: Warn on production changes without review\n\n### Pending Tasks\n- ❗ Review outcome for dec-b1c2 (architecture, 12 days overdue)\n\n### Confirmed Patterns\n- Stateless auth scales better (3x confirmed)\n- Always validate input at API boundary (5x confirmed)\n\n### Decision Protocol\nUse `pre_action` tool before any significant decision.\nInclude: confidence, category, stakes, 2+ reasons, tags, pattern."
  }
}

Use Cases

1. Claude Code CLI - system prompt injection:

# In CLAUDE.md (auto-generated or templated)
{{cstp_session_context}}

A build script or pre-hook calls getSessionContext and injects the markdown into CLAUDE.md before the session starts.

2. OpenClaw - agent initialization:

# In agent startup
context = await cstp.get_session_context(
    agent_id="emerson",
    task_description=current_task,
    format="markdown"
)
system_prompt += context["markdown"]

3. LangChain / CrewAI / AutoGen:

# As a tool or system message
context = cstp_client.get_session_context(agent_id="agent-1", task="...")
agent = Agent(system_message=base_prompt + context.markdown)

4. Periodic refresh (long sessions): Call getSessionContext every N turns to refresh decisions and ready queue as the session evolves.

MCP Tool Definition

{
  "name": "get_session_context",
  "description": "Get full cognitive context for this session: relevant past decisions, calibration profile, active guardrails, pending tasks, and confirmed patterns. Call at session start or when switching tasks.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_description": { "type": "string", "description": "What you're working on this session" },
      "include": {
        "type": "array",
        "items": { "type": "string", "enum": ["decisions", "guardrails", "calibration", "ready", "patterns", "contradictions"] },
        "default": ["decisions", "guardrails", "calibration", "ready", "patterns"]
      },
      "decisions_limit": { "type": "integer", "default": 10 },
      "ready_limit": { "type": "integer", "default": 5 },
      "format": { "type": "string", "enum": ["json", "markdown"], "default": "markdown" }
    },
    "required": ["task_description"]
  }
}

Design Principles

Session-level, not decision-level. F046 (preAction) is called per decision. F047 is called once at session start (or on task switch).
Markdown-first. Most agent frameworks inject context as text. The markdown format is ready to paste into any system prompt.
Progressive disclosure. The include array lets lightweight agents request only what they need. Full context for complex agents, just guardrails for simple ones.
Framework-agnostic. JSON-RPC + MCP. Works with Claude Code, OpenClaw, LangChain, CrewAI, raw curl.

Phases

P1: Core endpoint - decisions + guardrails + calibration
P2: Ready queue + patterns + contradictions
P3: Markdown formatting + MCP tool
P4: Auto-refresh middleware for long sessions

Integration Points

F002 (Query): Task-scoped decision retrieval
F003 (Guardrails): Active guardrail listing
F009 (Calibration): Per-agent, per-category calibration
F027 (Quality): Confirmed patterns from quality-scored decisions
F044 (Work Discovery): Ready queue integration
F045 (Graph): Graph-neighbor decisions in context
F046 (Pre-Action): Session context is the complement - F047 loads context, F046 gates individual decisions