Context Attachment: Terminal Agent Session Management Infrastructure

Purpose of This Document

This document provides context for a Perplexity research inquiry about Anemoi A2A communication patterns. It describes our current infrastructure so research can identify where Anemoi patterns would provide concrete improvements.

Current Architecture Overview

Session Lifecycle Management

We operate a UUID-tracked session orchestration system for Claude Code terminal agents:

``` ┌─────────────────────────────────────────────────────────────────┐ │ SESSION LIFECYCLE │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ newsessionuuid <namespace> │ │ │ │ │ ▼ │ │ ┌─────────────┐ ┌──────────────────┐ ┌───────────────┐ │ │ │ Generate │───▶│ Pre-Launch Agent │───▶│ Main Session │ │ │ │ UUID + │ │ (Haiku model) │ │ (User model) │ │ │ │ Metadata │ │ Creates CONTEXT │ │ Reads CONTEXT │ │ │ └─────────────┘ └──────────────────┘ └───────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ env.sh exports CONTEXT.md Langfuse │ │ LAUNCH_*.sh Langfuse Trace Observations │ │ Session aliases Redis cache via Hooks │ │ │ └─────────────────────────────────────────────────────────────────┘ ```

Key Components

1. Session Creation (newsessionuuid)

Creates tracked sessions with:

• UUID generation: Unique session identifier
• Namespace: Human-readable session category
• MCP configs: Which tool servers are available
• Add directories: Filesystem context for the agent
• Launcher script: LAUNCH__session_id_<namespace>_<timestamp>.sh

Outputs to _env.sh: ```bash session_id__MyNamespace_2512301200=<uuid> alias resume_MyNamespace="claude --mcp-config $MCP --add-dir $DIR --resume $UUID" alias fork_MyNamespace="claude --mcp-config $MCP --add-dir $DIR --resume $UUID --fork-session" ```

2. Pre-Launch Context Agent (miette_newsession_context.sh)

Critical pattern: Before main session starts, a lightweight agent (Haiku) analyzes the session intentions and creates:

• CONTEXT.md in session directory — summarizes what the session will CREATE
• Langfuse trace with session metadata
• Redis cache entry pointing to context file

This agent receives webhook payload: ```json { "session": { "id": "<uuid>", "namespace": "MyNamespace", "prompt": "User's initial prompt...", "mcpConfigs": ["/path/to/mcp.json"], "addDirs": ["/src", "/workspace"], "sessionDir": "/src/_sessiondata/<uuid>", "launcherPath": "LAUNCH__session_id_MyNamespace.sh" } } ```

Current limitation: Context transfer is FILE-BASED. The pre-launch agent writes to disk, main agent reads from disk. No direct agent-to-agent communication.

3. Session Observability (v2_claude_hooks)

Hook system captures session lifecycle to Langfuse:

State maintained in ._langfuse_state: ```bash TRACE_ID=<session_id> LAST_USER_INPUT_OBS_ID=<uuid> PLAN_COUNT=1 TOOL_COUNT=5 INTERACTION_COUNT=1 ```

4. Fork/Resume Pattern

Sessions can fork (branch) while maintaining parent reference: ```bash claude --resume $parent_uuid --fork-session --session-id $child_uuid ```

Current limitation: Forked session inherits conversation history but loses:

• Parent's Langfuse trace context
• Parent's structural tension state
• Parent's assumption log

Current Context Transfer Methods

Problem: No direct agent-to-agent communication channel. All context passes through intermediaries (files, databases, webhooks).

Identified Pain Points

1. Context Bloat in Fork Operations

When forking, the child session must either:

• Re-inject full parent context (token expensive)
• Or lose semantic continuity (breaks workflow)

2. Pre-Launch Agent Isolation

The Haiku agent preparing CONTEXT.md cannot:

• Query the main session about preferences
• Receive feedback if context was useful
• Adapt based on session progress

3. Parallel Agent Coordination

Running multiple Claude instances requires:

• Manual state synchronization
• File-based handoffs
• No real-time awareness of sibling agents

4. Hook-to-Hook Communication

Each hook operates independently. No mechanism for:

• pre_tool_use_hook to inform post_tool_use_hook of expectations
• Cross-session hook coordination

What We Want to CREATE (Desired Outcomes)

1. Direct A2A Channel: Agents communicate structured messages without file intermediaries
2. Context Inheritance Protocol: Forked sessions receive semantic context, not just conversation dumps
3. Bidirectional Pre-Launch: Preparation agent and main agent can negotiate context needs
4. Coordinated Multi-Agent: Parallel sessions share discoveries in real-time
5. Stateful Hook Chain: Hooks pass structured data through session lifecycle

Research Questions for Anemoi

Given this infrastructure, we need to understand:

1. Anemoi's communication topology: Does it use message passing, shared memory, or hybrid?

2. Integration surface: Can Anemoi patterns work with:

   • Shell-based session launchers?
   • MCP tool servers?
   • Langfuse trace hierarchy?

3. State preservation: How does Anemoi handle:

   • Session continuation after interruption?
   • Context transfer during agent handoff?
   • Genealogical tracking (parent-child relationships)?

4. Comparison to alternatives:

   • vs. Agent Continuations (Snaplogic) — JSON state blobs
   • vs. NCP storyforms — narrative intent objects
   • vs. MCP-Zero — dynamic tool discovery

5. Terminal agent applicability:

   • Is Anemoi designed for API-based agents only?
   • Can CLI agents (Claude Code) participate in Anemoi networks?
   • What's the minimal integration for session fork/resume?

Existing Academic Validation (From Prior Research)

Our previous Perplexity conversation validated these patterns:

Gap identified: Anemoi's A2A pattern was mentioned but not explored. Quote from prior research:

"Anemoi (GitHub: Coral-Protocol/Anemoi) — A2A communication pattern for inter-agent collaboration. Shows how structured direct communication beats prompt concatenation."

This is what we want to explore deeply.

Success Criteria for Research Output

The research will be useful if it provides:

1. Concrete protocol description: How Anemoi agents exchange messages (format, transport, semantics)
2. Implementation examples: Code patterns showing A2A communication
3. Integration pathway: Steps to add Anemoi patterns to existing shell-based orchestration
4. Trade-off analysis: When A2A direct communication is better vs. file-based handoffs
5. Self-inquiry questions: What we should ask ourselves before implementing

File References (For Context Only)

These files exist in our system and inform this context:

• /src/scripts/fn_llm.sh — Contains newsessionuuid function
• /src/scripts/v2_claude_hooks/ — Hook system for Langfuse integration
• /src/miette/claude-plan-insights/miette_newsession_context.sh — Pre-launch agent script
• /src/_sessiondata/<uuid>/ — Session data directories

Perplexity cannot access these files, but understanding they exist helps frame the research toward practical integration.