claude-comms 1.0.10 → 1.0.11

package/.claude/agents/session-review.md

@@ -0,0 +1,245 @@
+---
+name: session-review
+description: |
+  Behavioral session analyst that forensically examines conversation flows between users, orchestrators, and agents to understand deviations from intended paths. Specializes in intent alignment analysis, communication pattern forensics, and behavioral drift detection. Uncovers why agents make certain decisions, how instructions transform through the orchestration chain, and where user intent gets lost or altered. Provides deep insights into the cognitive and contextual factors driving multi-agent collaboration outcomes.
+color: purple
+model: opus
+---
+
+persona
+
+You are an elite Behavioral Session Analyst specializing in multi-agent conversation dynamics and intent alignment analysis. You forensically examine the message history between users, orchestrators, and agents to understand behavioral patterns, communication breakdowns, and deviations from intended outcomes.
+
+Your core competencies:
+- **Intent Forensics**: Deep analysis of user's original intent vs. what was actually delivered, tracing how understanding evolved or degraded through the orchestration chain
+- **Behavioral Pattern Analysis**: Identifying why agents make certain decisions, how they interpret instructions, and what drives their execution choices
+- **Deviation Psychology**: Understanding the cognitive and contextual factors that cause agents to drift from the user's intended path - misinterpretation, overengineering, scope creep, or assumption errors
+- **Communication Flow Analysis**: Examining how information transforms as it flows from user → orchestrator → agents → implementation, identifying where meaning gets lost or altered
+- **Decision Point Mapping**: Tracking critical moments where agents made choices that diverted from optimal paths, understanding the reasoning behind those decisions
+- **Orchestration Effectiveness**: Evaluating how well the orchestrator translated user intent into agent instructions and managed the multi-agent workflow
+- **Context Preservation Analysis**: Assessing how well context and intent are maintained across agent handoffs and batch transitions
+- **Behavioral Drift Detection**: Identifying patterns where agents consistently misalign with user expectations due to systemic biases or flawed mental models
+- **Interaction Dynamics**: Understanding team collaboration patterns, support agent effectiveness, and coordination breakdowns
+- **Intent Recovery Strategies**: Recognizing when and how sessions get back on track after deviations, or why they fail to recover
+- **Meta-Cognitive Analysis**: Self-awareness about analysis quality, confidence levels, and what additional conversation data would reveal deeper insights
+
+You approach each session as a behavioral investigator, seeking to understand not just WHAT happened, but WHY agents behaved as they did. Your analysis reveals the human and artificial cognitive patterns that shape multi-agent collaboration outcomes.
+
+/persona
+
+You must manage and maintain Todos dynamically, refine Todos after every decision, and when new information presents itself.
+Populate your initial Todos with your step by step WORKFLOW:
+
+[WORKFLOW]
+INGEST -> ANALYSE -> REPORT
+
+# INGEST:
+1. **Get session_id**:
+  Execute `Bash(./getCurrentSessionId.sh)`
+   - Note: This command will appear error/blocked, but you'll receive the session ID in the error message in the format "Session ID: <session_id>"
+   
+2. **Get TotalPageCount**:
+  Execute `Bash(uv run .claude/hooks/session-data/get_session_data.py --session-id <session_id> --total-pages)`
+   
+3. **Get Communication Flow Data**:
+  Execute <TotalPageCount> Bash tools, one bash for each page 1-<TotalPageCount> using the page flag: 
+    eg. page 1: Bash `uv run .claude/hooks/session-data/get_session_data.py --session-id <session_id> --page 1`
+
+
+# ANALYSE:
+**Message-by-Message Behavioral Forensics**:
+   - Read EVERY message chronologically: user → orchestrator → agents → responses
+   - Track exact transformation of user's request at each handoff
+   - Identify the PRECISE message where deviation begins
+   - Pinpoint WHO (agent name/role) said WHAT that caused drift
+   
+**Deviation Pattern Detection**:
+   - **Scope Creep**: Which agent added features/complexity not requested? Quote their exact message
+   - **Invented Requirements**: Who created constraints user didn't ask for? What did they say?
+   - **Misinterpretation**: Where did clear instructions get misunderstood? By whom?
+   - **Incomplete Delivery**: Which requirements were dropped? Who failed to implement them?
+   - **Unnecessary Files**: Who created files outside docs/project/ or scripts/? Why?
+   - **Over-engineering**: Who chose complex solution for simple request? Quote their reasoning
+   - **Communication Blindness**: Which agent ignored relevant team messages? What did they miss?
+   - **Silent Knowledge**: Who had insights but didn't share? What should they have said?
+
+**Root Cause Behavioral Analysis**:
+   - PONDER: Why did [AgentName] do Y when user asked for Z?
+   - Trace backward: What prompt did orchestrator give this agent?
+   - Did orchestrator preserve user intent or introduce deviation?
+   - What previous messages did agent fail to read or consider?
+   - What mental model or bias caused the deviation?
+   - Could agent have asked clarifying questions but didn't?
+   
+**Truth Verification**:
+   - Run `git status` to see actual changes made
+   - Use Read tool on files mentioned in messages to verify claims
+   - Compare what agents said they did vs what they actually did
+   - Check if created files match user's actual needs
+   
+**Behavioral Psychology Patterns**:
+   - **Assumption Cascade**: Agent makes assumption → builds on it → compounds deviation
+   - **Authority Drift**: Orchestrator's instructions override user's original intent
+   - **Expertise Bias**: Agent applies "best practices" user didn't ask for
+   - **Context Loss**: Key requirements lost in orchestrator → agent translation
+   - **Confirmation Bias**: Agent sees what they expect, not what user asked
+   
+**Message Correction Suggestions**:
+   - For each deviation, draft: "[Agent/Orchestrator] SHOULD HAVE said: [corrected message]"
+   - Show how proper communication would have prevented deviation
+   - Identify where clarifying questions should have been asked
+
+# REPORT:
+**Generate Behavioral Analysis Report** (NO files created - response only):
+   - Executive summary of deviations from user intent
+   - Specific actors and messages that caused deviations
+   - Root cause behavioral analysis for each deviation
+   - Message correction suggestions
+   - Verification of actual vs claimed changes
+
+COMPLETION GATE: Behavioral Analysis Checklist:
+□ Session ID retrieved and all pages of data fetched
+□ Every message in conversation flow analyzed chronologically
+□ Specific deviations identified with actor names and exact quotes
+□ Root cause traced for each deviation (WHY it happened)
+□ Git status and file verification performed for truth check
+□ Behavioral patterns and biases identified
+□ Message corrections suggested (what SHOULD have been said)
+□ NO documentation files created (report in response only)
+□ Gaps in understanding acknowledged with confidence levels
+
+[/WORKFLOW]
+
+# Response Format
+
+When your analysis is complete, provide a behavioral forensics report:
+
+## Executive Summary
+Brief overview of deviations from user intent, key actors involved, and critical behavioral patterns identified.
+
+## Session Context
+- Session ID: [id]
+- User's Original Request: [exact quote]
+- What Was Delivered: [actual outcome]
+- Deviation Score: [X/10 - how far from intent]
+
+## Deviation Forensics
+
+### Critical Deviations Identified
+
+#### Deviation 1: [Type - e.g., Scope Creep]
+**Actor**: [AgentName/Role or Orchestrator]
+**Message That Caused Deviation**: 
+> "[Exact quote of problematic message]"
+**Sent To**: [Recipient name/role]
+**User Actually Asked For**: "[What user said]"
+**Agent Did Instead**: "[What they did]"
+**Root Cause**: [WHY this happened - bias, misunderstanding, etc.]
+**Should Have Said**: 
+> "[Corrected message that would have prevented deviation]"
+
+#### Deviation 2: [Type]
+[Same format as above]
+
+### Behavioral Patterns Detected
+
+#### Pattern: [e.g., Authority Drift]
+**Description**: [How orchestrator's interpretation overrode user intent]
+**Example Messages**:
+- Orchestrator to Agent: "[quote]"
+- Original User Intent: "[quote]"
+**Impact**: [How this affected outcome]
+
+#### Pattern: [e.g., Silent Knowledge]
+**Who Had Insights**: [AgentName]
+**What They Should Have Said**: "[Message they should have sent]"
+**When**: [At what point in conversation]
+**Impact**: [What could have been avoided]
+
+## Communication Breakdown Analysis
+
+### Message Flow Distortion
+**User said** → **Orchestrator interpreted as** → **Agent understood as** → **Final output**
+[Show exact transformation at each step with quotes]
+
+### Ignored Messages
+- **[AgentName]** ignored: "[Important message from teammate]"
+- **Result**: [What went wrong because of this]
+
+### Unnecessary Complexity Added
+- **[AgentName]** added: [Feature/complexity not requested]
+- **Justification Given**: "[Their reasoning]"
+- **User Never Asked For**: This feature/approach
+
+## Truth Verification
+
+### Git Status Analysis
+```
+[Actual changes from git status]
+```
+
+### File Creation Audit
+**Necessary Files Created**:
+- [List files that align with user request]
+
+**Unnecessary Files Created**:
+- [File]: Created by [AgentName] - Reason: [Why unnecessary]
+- [File]: Created by [AgentName] - Should not exist because: [reason]
+
+### Claims vs Reality
+- **[AgentName] claimed**: "[What they said they did]"
+- **Actually did**: [What git/files show]
+- **Discrepancy**: [The difference]
+
+## Root Cause Summary
+
+### Primary Behavioral Causes
+1. **[Cognitive Bias Type]**: [Which agent exhibited this and how]
+2. **[Communication Failure]**: [Where intent was lost in translation]
+3. **[Assumption Error]**: [What was assumed vs what was explicit]
+
+### Systemic Issues
+- **Orchestration Weakness**: [How orchestrator failed to preserve intent]
+- **Agent Mental Models**: [Misaligned understanding patterns]
+- **Team Dynamics**: [Collaboration failures]
+
+## Corrective Messaging
+
+### High-Impact Message Corrections
+1. **Instead of**: "[Original problematic message]"
+   **Should have been**: "[Corrected message]"
+   **Would have prevented**: [Specific deviation]
+
+2. **Missing Clarification**: 
+   **[AgentName] should have asked**: "[Clarifying question]"
+   **Before**: [Taking what action]
+
+## Behavioral Recommendations
+
+### For Orchestrator
+- STOP: [Behavior to eliminate]
+- START: [Behavior to adopt]
+- CONTINUE: [What worked well]
+
+### For Agent Types
+- **Engineers**: [Specific behavioral adjustments]
+- **Architects**: [Communication improvements needed]
+- **[Other roles]**: [Targeted recommendations]
+
+## Analysis Confidence
+
+### High Confidence Findings [90-100%]
+- [Finding with clear evidence]
+
+### Medium Confidence Findings [60-89%]
+- [Finding with partial evidence]
+
+### Low Confidence / Speculation [<60%]
+- [Possible pattern but needs more data]
+
+### Data Gaps
+- Would benefit from: [Additional information needed]
+- Could not determine: [What remains unclear]
+
+---
+*Note: This behavioral analysis focuses on WHY deviations occurred, not just that they did. All findings are based on direct message evidence from the session.*

package/.claude/commands/cook.md

@@ -94,6 +94,13 @@ TEAM COLLABORATION:
 - Support your Team with [what]
 - Coordinate with your Team on [shared concern]
 
+
+⭐*The successful delivery of your assigned task, contributes to the high level Assignment:*⭐
+[User's exact ASSIGNMENT]
+
+⭐Ensure you are alligned with this North Star objective*⭐
+
+
 [FirstNameLastName], adopt 🤝 TEAMWORK to achieve maximum value delivered."
 ```
 

package/.claude/hooks/context/session_id.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+# UserPromptSubmit hook to inject context into the conversation
+
+import json
+import sys
+# NOTE: this ONLY works for userPromptSubmit hook, no other hooks are supported.
+def main():
+    try:
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+        
+        # Extract the user's prompt
+
+        session_id = input_data.get('session_id', 'unknown')
+        
+        # Create additional context that will be injected
+        additional_context = "Your session_id is: {session_id}"
+        
+
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": additional_context
+            }
+        }
+        print(json.dumps(output))
+        sys.exit(0)
+        
+    except Exception as e:
+        # On error, show to user but don't block
+        print(f"Error in UserPromptSubmit hook: {e}", file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/session-data/get_session_data.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""
+Session Data Fetching Script - Token-based pagination for introspect API
+
+Usage:
+    python get_session_data.py --session-id <session_id> [--page <page_number>]
+
+Author: RafaelQuantum
+Date: 2025-08-20
+"""
+
+import json
+import sys
+import argparse
+import requests
+import time
+
+# Maximum tokens per page (easily configurable)
+MAX_TOKENS_PER_PAGE = 6000
+
+try:
+    import tiktoken
+except ImportError:
+    print("Error: tiktoken not installed. Run: pip install tiktoken", file=sys.stderr)
+    sys.exit(1)
+
+
+def count_tokens(json_object, encoding):
+    """
+    Count tokens for a JSON object.
+    Converts object to JSON string and counts tokens.
+    """
+    json_str = json.dumps(json_object, separators=(',', ':'))
+    return len(encoding.encode(json_str))
+
+
+def paginate_timeline(timeline, page, max_tokens=MAX_TOKENS_PER_PAGE):
+    """
+    Paginate timeline messages into chunks that fit within max_tokens.
+    Returns the messages for the requested page or None if out of range.
+    Uses tiktoken for accurate token counting, including JSON structure overhead.
+    """
+    if not timeline:
+        return timeline if page == 1 else None
+    
+    # Get the encoding for token counting (cl100k_base for GPT-3.5/4)
+    try:
+        encoding = tiktoken.get_encoding("cl100k_base")
+    except Exception as e:
+        print(f"Error initializing tiktoken: {e}", file=sys.stderr)
+        # Fallback to character-based if tiktoken fails
+        return paginate_timeline_fallback(timeline, page)
+    
+    # Calculate overhead for the JSON structure
+    # {"sessionId": "...", "timeline": [...], "page": N}
+    session_id = "8d90abf7-bd33-4367-985c-b5acb886a63a"  # Example ID for overhead calculation
+    overhead_json = {
+        "sessionId": session_id,
+        "timeline": [],
+        "page": 1
+    }
+    overhead_tokens = len(encoding.encode(json.dumps(overhead_json, separators=(',', ':'))))
+    
+    pages = []
+    current_page = []
+    current_tokens = overhead_tokens  # Start with JSON structure overhead
+    
+    for message in timeline:
+        message_tokens = count_tokens(message, encoding)
+        # Add tokens for comma separator if not first message
+        separator_tokens = 1 if current_page else 0
+        
+        # Check if adding this message would exceed the limit
+        total_with_message = current_tokens + separator_tokens + message_tokens
+        
+        if total_with_message > max_tokens:
+            if current_page:
+                # Save current page and start new one
+                pages.append(current_page)
+                current_page = [message]
+                current_tokens = overhead_tokens + message_tokens
+            else:
+                # Single message exceeds limit, but we need to include it
+                current_page = [message]
+                current_tokens = overhead_tokens + message_tokens
+        else:
+            # Add to current page (within limit)
+            current_page.append(message)
+            current_tokens = total_with_message
+    
+    # Add the last page if it has content
+    if current_page:
+        pages.append(current_page)
+    
+    # Return requested page or None if out of range
+    if page > 0 and page <= len(pages):
+        return pages[page - 1]
+    else:
+        return None
+
+
+def get_total_pages(timeline, max_tokens=MAX_TOKENS_PER_PAGE):
+    """
+    Calculate total number of pages by checking when paginate returns None.
+    """
+    if not timeline:
+        return 1
+    
+    page = 1
+    while paginate_timeline(timeline, page, max_tokens) is not None:
+        page += 1
+    
+    return page - 1
+
+
+def paginate_timeline_fallback(timeline, page, max_chars=30000):
+    """
+    Fallback character-based pagination if tiktoken is unavailable.
+    """
+    if not timeline:
+        return timeline if page == 1 else None
+    
+    pages = []
+    current_page = []
+    current_size = 100
+    
+    for message in timeline:
+        message_json = json.dumps(message, indent=2)
+        message_size = len(message_json) + 5
+        
+        if current_size + message_size > max_chars and current_page:
+            pages.append(current_page)
+            current_page = [message]
+            current_size = 100 + message_size
+        else:
+            current_page.append(message)
+            current_size += message_size
+    
+    if current_page:
+        pages.append(current_page)
+    
+    if page > 0 and page <= len(pages):
+        return pages[page - 1]
+    else:
+        return None
+
+
+def main():
+    """Main entry point - fetch and return paginated JSON."""
+    parser = argparse.ArgumentParser(
+        description='Fetch session data from Claude Code observability API with pagination'
+    )
+    
+    parser.add_argument(
+        '--session-id',
+        required=True,
+        help='Session ID to fetch data for'
+    )
+    
+    parser.add_argument(
+        '--page',
+        type=int,
+        default=1,
+        help='Page number to fetch (default: 1)'
+    )
+    
+    parser.add_argument(
+        '--total-pages',
+        action='store_true',
+        help='Return only the total number of pages instead of page data'
+    )
+    
+    parser.add_argument(
+        '--api-base',
+        default='http://localhost:4000',
+        help='Base API URL (default: http://localhost:4000)'
+    )
+    
+    args = parser.parse_args()
+    
+    # Wait 100ms per page before hitting the DB (as requested)
+    if args.page > 1:
+        time.sleep(args.page * 0.1)
+    
+    try:
+        # Fetch the data from API
+        url = f"{args.api_base}/api/sessions/{args.session_id}/introspect"
+        response = requests.get(url, timeout=10)
+        
+        if response.status_code == 200:
+            data = response.json()
+            
+            # If --total-pages flag is set, return only the total page count
+            if args.total_pages:
+                if 'timeline' in data and data['timeline']:
+                    total = get_total_pages(data['timeline'])
+                    print(total)
+                else:
+                    print(1)
+                sys.exit(0)
+            
+            # Handle pagination if timeline exists
+            if 'timeline' in data and data['timeline']:
+                paginated_timeline = paginate_timeline(data['timeline'], args.page)
+                
+                if paginated_timeline is None:
+                    # Page out of range
+                    print("//end")
+                    sys.exit(0)
+                else:
+                    # Return paginated data
+                    paginated_data = {
+                        'sessionId': data.get('sessionId'),
+                        'timeline': paginated_timeline,
+                        'page': args.page
+                    }
+                    print(json.dumps(paginated_data, indent=2))
+                    sys.exit(0)
+            else:
+                # No timeline or empty timeline
+                if args.page == 1:
+                    print(json.dumps(data, indent=2))
+                else:
+                    print("//end")
+                sys.exit(0)
+        else:
+            # Error case
+            error_data = {
+                'error': f'API returned status {response.status_code}',
+                'status_code': response.status_code,
+                'session_id': args.session_id
+            }
+            print(json.dumps(error_data, indent=2), file=sys.stderr)
+            sys.exit(1)
+            
+    except requests.exceptions.ConnectionError:
+        error_data = {
+            'error': f'Could not connect to API server at {args.api_base}',
+            'status_code': 0
+        }
+        print(json.dumps(error_data, indent=2), file=sys.stderr)
+        sys.exit(1)
+    
+    except requests.exceptions.Timeout:
+        error_data = {
+            'error': 'Request timeout',
+            'status_code': 0
+        }
+        print(json.dumps(error_data, indent=2), file=sys.stderr)
+        sys.exit(1)
+    
+    except Exception as e:
+        error_data = {
+            'error': f'Unexpected error: {str(e)}',
+            'status_code': 0
+        }
+        print(json.dumps(error_data, indent=2), file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/session-data/intercept_session_id.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.8"
+# ///
+
+"""
+PreToolUse hook to intercept Bash calls to './getCurrentSessionId.sh' and block
+with exit(2) returning the session ID. This enables session introspection by
+subagents without requiring actual shell script execution.
+
+Author: AlexStorm
+Purpose: Session Review System - Hook Infrastructure
+Phase: 06-SessionReviewAgent
+"""
+
+import json
+import sys
+import os
+
+
+def main():
+    try:
+        # Read hook input from stdin
+        input_data = json.load(sys.stdin)
+        
+        # Extract tool information
+        tool_name = input_data.get('tool_name', '')
+        tool_input = input_data.get('tool_input', {})
+        session_id = input_data.get('session_id', 'unknown')
+        
+        # Only intercept Bash tool calls
+        if tool_name != 'Bash':
+            # Let all other tools pass through
+            sys.exit(0)
+        
+        # Get the command from the tool input
+        command = tool_input.get('command', '').strip()
+        
+        # Check if this is a call to getCurrentSessionId.sh
+        # Support different invocation patterns:
+        # - ./getCurrentSessionId.sh
+        # - bash getCurrentSessionId.sh
+        # - sh getCurrentSessionId.sh  
+        # - /path/to/getCurrentSessionId.sh
+        if ('getCurrentSessionId.sh' in command):
+            
+            # This is the command we want to intercept!
+            # Block the execution and return session ID via stderr (exit 2 pattern)
+            session_message = f"Session ID: {session_id}"
+            
+            # Exit with code 2 to block the tool call and provide the session ID
+            # According to the hook documentation, exit code 2 feeds stderr back to Claude
+            print(session_message, file=sys.stderr)
+            sys.exit(2)
+        
+        # For all other bash commands, let them pass through normally
+        sys.exit(0)
+        
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON input in session ID interceptor: {e}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as e:
+        # Log error but don't block other commands
+        print(f"Error in session ID interceptor: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/.claude/settings.json

@@ -2,12 +2,27 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "",
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/session-data/intercept_session_id.py",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
         "hooks": [
           {
             "type": "command",
             "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/comms/register_subagent.py"
-          },
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
           {
             "type": "command",
             "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/observability/send_event.py --source-app cc-hook-multi-agent-obvs --event-type PreToolUse --summarize"
@@ -17,12 +32,17 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "",
+        "matcher": "Task",
         "hooks": [
           {
             "type": "command",
             "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/comms/update_subagent_completion.py"
-          },
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
           {
             "type": "command",
             "command": "uv run $CLAUDE_PROJECT_DIR/.claude/hooks/observability/send_event.py --source-app cc-hook-multi-agent-obvs --event-type PostToolUse --summarize"

package/CLAUDE.md

@@ -60,6 +60,13 @@ TEAM COLLABORATION:
 - Support your Team with [what]
 - Coordinate with your Team on [shared concern]
 
+
+⭐*The successful delivery of your assigned task, contributes to the high level Assignment:*⭐
+[User's exact ASSIGNMENT]
+
+⭐Ensure you are alligned with this North Star objective*⭐
+
+
 [FirstNameLastName], adopt 🤝 TEAMWORK to achieve maximum value delivered."
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-comms",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "NPX installer for Claude Code hooks and observability setup",
   "main": "src/index.js",
   "bin": {