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 │ │ │ │ │ ▼ │ │ ┌─────────────┐ ┌──────────────────┐ ┌───────────────┐ │ │ │ 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= 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": "", "namespace": "MyNamespace", "prompt": "User's initial prompt...", "mcpConfigs": ["/path/to/mcp.json"], "addDirs": ["/src", "/workspace"], "sessionDir": "/src/_sessiondata/", "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= 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.