stravinsky 0.2.40__py3-none-any.whl → 0.3.4__py3-none-any.whl

mcp_bridge/hooks/session_idle.py

@@ -0,0 +1,116 @@
+"""
+Session Idle Hook - Stop Hook Implementation.
+
+Detects when session becomes idle with incomplete todos and injects
+a continuation prompt to force task completion.
+
+Based on oh-my-opencode's todo-continuation-enforcer pattern.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Continuation prompt injected when session is idle with incomplete todos
+TODO_CONTINUATION_PROMPT = """
+[SYSTEM REMINDER - TODO CONTINUATION]
+
+You have incomplete tasks in your todo list. Continue working on the next pending task.
+
+RULES:
+- Proceed immediately without asking for permission
+- Mark the current task as in_progress before starting
+- Mark each task complete when finished
+- Do NOT stop until all tasks are done
+- If blocked, create a new task describing what needs to be resolved
+
+STATUS CHECK:
+Use TodoWrite to check your current task status and continue with the next pending item.
+"""
+
+# Track sessions to prevent duplicate injections
+_idle_sessions: Dict[str, bool] = {}
+_last_activity: Dict[str, float] = {}
+
+
+async def session_idle_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Pre-model-invoke hook that detects idle sessions with incomplete todos.
+
+    Checks if:
+    1. The conversation has pending todos
+    2. The session has been idle (no recent tool calls)
+    3. A continuation hasn't already been injected
+
+    If all conditions met, injects TODO_CONTINUATION_PROMPT.
+    """
+    import time
+
+    prompt = params.get("prompt", "")
+    session_id = params.get("session_id", "default")
+
+    # Skip if already contains continuation reminder
+    if "[SYSTEM REMINDER - TODO CONTINUATION]" in prompt:
+        return None
+
+    # Skip if this is a fresh prompt (user just typed something)
+    if params.get("is_user_message", False):
+        _last_activity[session_id] = time.time()
+        _idle_sessions[session_id] = False
+        return None
+
+    # Check for pending todos in the prompt/context
+    has_pending_todos = _detect_pending_todos(prompt)
+
+    if not has_pending_todos:
+        return None
+
+    # Check idle threshold (2 seconds of no activity)
+    current_time = time.time()
+    last_activity = _last_activity.get(session_id, current_time)
+    idle_seconds = current_time - last_activity
+
+    if idle_seconds < 2.0:
+        return None
+
+    # Check if already injected for this idle period
+    if _idle_sessions.get(session_id, False):
+        return None
+
+    # Mark as injected and inject continuation
+    _idle_sessions[session_id] = True
+    logger.info(f"[SessionIdleHook] Injecting TODO continuation for session {session_id}")
+
+    modified_prompt = prompt + "\n\n" + TODO_CONTINUATION_PROMPT
+
+    return {**params, "prompt": modified_prompt}
+
+
+def _detect_pending_todos(prompt: str) -> bool:
+    """
+    Detect if there are pending todos in the conversation.
+
+    Looks for patterns like:
+    - [pending] or status: pending
+    - TodoWrite with pending items
+    - Incomplete task lists
+    """
+    pending_patterns = [
+        "[pending]",
+        "status: pending",
+        '"status": "pending"',
+        "pending tasks",
+        "incomplete tasks",
+        "remaining todos",
+    ]
+
+    prompt_lower = prompt.lower()
+    return any(pattern.lower() in prompt_lower for pattern in pending_patterns)
+
+
+def reset_session(session_id: str = "default"):
+    """Reset idle state for a session (call when user provides new input)."""
+    _idle_sessions[session_id] = False
+    import time
+    _last_activity[session_id] = time.time()

mcp_bridge/hooks/session_notifier.py

@@ -0,0 +1,125 @@
+"""
+Session Notification Hook.
+
+Provides OS-level desktop notifications when sessions are idle.
+"""
+
+import logging
+import platform
+import subprocess
+from typing import Any, Dict, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+# Track which sessions have been notified (avoid duplicates)
+_notified_sessions: Set[str] = set()
+
+
+def get_notification_command(title: str, message: str, sound: bool = True) -> Optional[list]:
+    """
+    Get platform-specific notification command.
+
+    Returns command as list of args, or None if platform not supported.
+    """
+    system = platform.system()
+
+    if system == "Darwin":  # macOS
+        # Use osascript for macOS notifications
+        script = f'display notification "{message}" with title "{title}"'
+        if sound:
+            script += ' sound name "Glass"'
+        return ["osascript", "-e", script]
+
+    elif system == "Linux":
+        # Use notify-send for Linux
+        cmd = ["notify-send", title, message]
+        if sound:
+            cmd.extend(["--urgency=normal"])
+        return cmd
+
+    elif system == "Windows":
+        # Use PowerShell for Windows notifications
+        ps_script = f"""
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+
+$template = @"
+<toast>
+    <visual>
+        <binding template="ToastGeneric">
+            <text>{title}</text>
+            <text>{message}</text>
+        </binding>
+    </visual>
+</toast>
+"@
+
+$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+$xml.LoadXml($template)
+$toast = New-Object Windows.UI.Notifications.ToastNotification $xml
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Stravinsky").Show($toast)
+"""
+        return ["powershell", "-Command", ps_script]
+
+    return None
+
+
+async def session_notifier_hook(
+    session_id: str,
+    has_pending_todos: bool,
+    idle_seconds: float,
+    params: Dict[str, Any]
+) -> None:
+    """
+    Session idle hook that sends desktop notification.
+
+    Called when session becomes idle with pending work.
+    """
+    # Skip if already notified for this session
+    if session_id in _notified_sessions:
+        return
+
+    # Skip if no pending work
+    if not has_pending_todos:
+        return
+
+    # Skip if idle time is too short (< 5 seconds)
+    if idle_seconds < 5.0:
+        return
+
+    # Prepare notification
+    title = "Stravinsky Session Idle"
+    message = f"Session has pending todos and has been idle for {int(idle_seconds)}s"
+
+    # Get platform-specific command
+    cmd = get_notification_command(title, message, sound=True)
+
+    if not cmd:
+        logger.warning(f"[SessionNotifier] Desktop notifications not supported on {platform.system()}")
+        return
+
+    try:
+        # Send notification (non-blocking)
+        subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True
+        )
+
+        # Mark as notified
+        _notified_sessions.add(session_id)
+        logger.info(f"[SessionNotifier] Sent desktop notification for session {session_id}")
+
+    except FileNotFoundError:
+        logger.warning(f"[SessionNotifier] Notification command not found: {cmd[0]}")
+    except Exception as e:
+        logger.error(f"[SessionNotifier] Failed to send notification: {e}")
+
+
+def clear_notification_state(session_id: str) -> None:
+    """
+    Clear notification state for a session (called when session resumes activity).
+    """
+    _notified_sessions.discard(session_id)

mcp_bridge/{native_hooks → hooks}/stravinsky_mode.py

@@ -3,12 +3,13 @@
 Stravinsky Mode Enforcer Hook
 
 This PreToolUse hook blocks native file reading tools (Read, Search, Grep, Bash)
-when stravinsky orchestrator mode is active, forcing use of agent_spawn instead.
+when stravinsky orchestrator mode is active, forcing use of Task tool for native
+subagent delegation.
 
 Stravinsky mode is activated by creating a marker file:
   ~/.stravinsky_mode
 
-The /strav:stravinsky command should create this file, and it should be
+The /stravinsky command should create this file, and it should be
 removed when the task is complete.
 
 Exit codes:
@@ -27,7 +28,7 @@ STRAVINSKY_MODE_FILE = Path.home() / ".stravinsky_mode"
 # Tools to block when in stravinsky mode
 BLOCKED_TOOLS = {
     "Read",
-    "Search", 
+    "Search",
     "Grep",
     "Bash",
     "MultiEdit",
@@ -38,8 +39,18 @@ BLOCKED_TOOLS = {
 ALLOWED_TOOLS = {
     "TodoRead",
     "TodoWrite",
-    "Task",
-    "Agent",  # MCP agent tools should be allowed
+    "Task",  # Native subagent delegation
+    "Agent",  # MCP agent tools
+}
+
+# Agent routing recommendations
+AGENT_ROUTES = {
+    "Read": "explore",
+    "Grep": "explore",
+    "Search": "explore",
+    "Bash": "explore",
+    "Edit": "code-reviewer",
+    "MultiEdit": "code-reviewer",
 }
 
 
@@ -65,33 +76,57 @@ def main():
     except json.JSONDecodeError:
         # If we can't parse input, allow the tool
         sys.exit(0)
-    
-    tool_name = hook_input.get("tool_name", "")
-    
+
+    tool_name = hook_input.get("toolName", hook_input.get("tool_name", ""))
+    params = hook_input.get("params", {})
+
     # Always allow certain tools
     if tool_name in ALLOWED_TOOLS:
         sys.exit(0)
-    
+
     # Check if stravinsky mode is active
     if not is_stravinsky_mode_active():
         # Not in stravinsky mode, allow all tools
         sys.exit(0)
-    
+
     config = read_stravinsky_mode_config()
-    
+
     # Check if this tool should be blocked
     if tool_name in BLOCKED_TOOLS:
+        # Determine which agent to delegate to
+        agent = AGENT_ROUTES.get(tool_name, "explore")
+
+        # Get tool context for better messaging
+        context = ""
+        if tool_name == "Grep":
+            pattern = params.get("pattern", "")
+            context = f" (searching for '{pattern[:30]}')"
+        elif tool_name == "Read":
+            file_path = params.get("file_path", "")
+            context = f" (reading {os.path.basename(file_path)})" if file_path else ""
+
+        # User-friendly delegation message
+        print(f"🎭 {agent}('Delegating {tool_name}{context}')", file=sys.stderr)
+
         # Block the tool and tell Claude why
         reason = f"""⚠️ STRAVINSKY MODE ACTIVE - {tool_name} BLOCKED
 
 You are in Stravinsky orchestrator mode. Native tools are disabled.
 
-Instead of using {tool_name}, you MUST use:
-  - stravinsky:agent_spawn with agent_type="explore" for file reading/searching
-  - stravinsky:agent_spawn with agent_type="dewey" for documentation
+Instead of using {tool_name}, you MUST use Task tool for native subagent delegation:
+  - Task(subagent_type="explore", ...) for file reading/searching
+  - Task(subagent_type="dewey", ...) for documentation research
+  - Task(subagent_type="code-reviewer", ...) for code analysis
+  - Task(subagent_type="debugger", ...) for error investigation
+  - Task(subagent_type="frontend", ...) for UI/UX work
+  - Task(subagent_type="delphi", ...) for strategic architecture decisions
 
 Example:
-  agent_spawn(agent_type="explore", prompt="Read and analyze the file at path/to/file.py")
+  Task(
+    subagent_type="explore",
+    prompt="Read and analyze the authentication module",
+    description="Analyze auth"
+  )
 
 To exit stravinsky mode, run:
   rm ~/.stravinsky_mode
@@ -100,7 +135,7 @@ To exit stravinsky mode, run:
         print(reason, file=sys.stderr)
         # Exit with code 2 to block the tool
         sys.exit(2)
-    
+
     # Tool not in block list, allow it
     sys.exit(0)
 

mcp_bridge/hooks/subagent_stop.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+SubagentStop hook: Handler for agent/subagent completion events.
+
+Fires when a Claude Code subagent (Task tool) finishes to:
+1. Output completion status messages
+2. Verify agent produced expected output
+3. Block completion if critical validation fails
+4. Integrate with TODO tracking
+
+Exit codes:
+  0 = Allow completion
+  2 = Block completion (force continuation)
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+STRAVINSKY_MODE_FILE = Path.home() / ".stravinsky_mode"
+
+
+def is_stravinsky_mode() -> bool:
+    """Check if stravinsky mode is active."""
+    return STRAVINSKY_MODE_FILE.exists()
+
+
+def extract_subagent_info(hook_input: dict) -> Tuple[str, str, str]:
+    """
+    Extract subagent information from hook input.
+
+    Returns: (agent_type, description, status)
+    """
+    # Try to get from tool parameters or response
+    params = hook_input.get("tool_input", hook_input.get("params", {}))
+    response = hook_input.get("tool_response", "")
+
+    agent_type = params.get("subagent_type", "unknown")
+    description = params.get("description", "")[:50]
+
+    # Determine status from response
+    status = "completed"
+    response_lower = response.lower() if isinstance(response, str) else ""
+    if "error" in response_lower or "failed" in response_lower:
+        status = "failed"
+    elif "timeout" in response_lower:
+        status = "timeout"
+
+    return agent_type, description, status
+
+
+def format_completion_message(agent_type: str, description: str, status: str) -> str:
+    """Format user-friendly completion message."""
+    icon = "✓" if status == "completed" else "✗"
+    return f"{icon} Subagent {agent_type} {status}: {description}"
+
+
+def should_block(status: str, agent_type: str) -> bool:
+    """
+    Determine if we should block completion.
+
+    Block if:
+    - Agent failed AND stravinsky mode active AND critical agent type
+    """
+    if status != "completed" and is_stravinsky_mode():
+        critical_agents = {"delphi", "code-reviewer", "debugger"}
+        if agent_type in critical_agents:
+            return True
+    return False
+
+
+def main():
+    """Main hook entry point."""
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        return 0
+
+    # Extract subagent info
+    agent_type, description, status = extract_subagent_info(hook_input)
+
+    # Output completion message
+    message = format_completion_message(agent_type, description, status)
+    print(message, file=sys.stderr)
+
+    # Check if we should block
+    if should_block(status, agent_type):
+        print(f"\n⚠️ CRITICAL SUBAGENT FAILURE - {agent_type} failed", file=sys.stderr)
+        print("Review the error and retry or delegate to delphi.", file=sys.stderr)
+        return 2
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_bridge/hooks/task_validator.py

@@ -0,0 +1,73 @@
+"""
+Task Validator Hook (empty-task-response-detector equivalent).
+
+Detects and warns about empty or failed Task tool execution results.
+"""
+
+import logging
+import re
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+EMPTY_PATTERNS = [
+    r"^\s*$",  # Completely empty
+    r"^null$",  # Null response
+    r"^None$",  # Python None
+    r"^undefined$",  # JavaScript undefined
+    r"^{}$",  # Empty JSON object
+    r"^\[\]$",  # Empty array
+]
+
+TASK_FAILURE_WARNING = """
+[TASK EXECUTION WARNING]
+The background task completed but returned empty or invalid output.
+
+Possible causes:
+- Agent terminated prematurely
+- Tool execution failed silently
+- Output was not captured properly
+- Task encountered an unhandled exception
+
+Recommended actions:
+1. Check task logs for errors
+2. Verify agent has proper tool access
+3. Re-run task with explicit error handling
+4. Use agent_progress(task_id) to monitor execution
+"""
+
+
+async def task_validator_hook(
+    tool_name: str, tool_input: Dict[str, Any], tool_response: str
+) -> str:
+    """
+    Post-tool-call hook that validates Task tool responses.
+
+    Detects empty/failed responses and injects diagnostic warning.
+    """
+    # Only validate Task tool responses
+    if tool_name not in ["Task", "agent_spawn"]:
+        return tool_response
+
+    # Skip if response is non-empty and meaningful
+    if tool_response and len(tool_response.strip()) > 50:
+        return tool_response
+
+    # Check for empty patterns
+    response_stripped = tool_response.strip()
+    for pattern in EMPTY_PATTERNS:
+        if re.match(pattern, response_stripped, re.IGNORECASE):
+            logger.warning(
+                f"[TaskValidator] Empty/invalid response detected for {tool_name}"
+            )
+            # Inject warning but preserve original response
+            return tool_response + "\n" + TASK_FAILURE_WARNING
+
+    # Check for suspiciously short responses (< 10 chars)
+    if len(response_stripped) < 10:
+        logger.warning(
+            f"[TaskValidator] Suspiciously short response ({len(response_stripped)} chars)"
+        )
+        return tool_response + "\n" + TASK_FAILURE_WARNING
+
+    return tool_response

mcp_bridge/hooks/tmux_manager.py

@@ -0,0 +1,141 @@
+"""
+Interactive Bash Session Hook (Tmux Manager).
+
+Manages persistent tmux sessions and cleanup.
+"""
+
+import logging
+import re
+import shlex
+import subprocess
+from typing import Any, Dict, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+# Track tmux sessions created by Stravinsky
+_tracked_sessions: Set[str] = set()
+SESSION_PREFIX = "stravinsky-"
+
+
+def parse_tmux_command(command: str) -> Optional[str]:
+    """
+    Parse tmux command to extract session name.
+
+    Handles quote/escape properly using shlex.
+    """
+    try:
+        # Use shlex to properly parse quoted arguments
+        parts = shlex.split(command)
+
+        # Look for tmux new-session or attach-session
+        if "tmux" not in parts:
+            return None
+
+        # Find session name after -t or -s flags
+        for i, part in enumerate(parts):
+            if part in ["-s", "-t"] and i + 1 < len(parts):
+                session_name = parts[i + 1]
+                return normalize_session_name(session_name)
+
+        # Check for inline session name (tmux new -s name)
+        for i, part in enumerate(parts):
+            if part == "new" or part == "new-session":
+                # Look for -s in following parts
+                for j in range(i + 1, len(parts)):
+                    if parts[j] == "-s" and j + 1 < len(parts):
+                        return normalize_session_name(parts[j + 1])
+
+    except Exception as e:
+        logger.error(f"[TmuxManager] Failed to parse tmux command: {e}")
+        return None
+
+    return None
+
+
+def normalize_session_name(name: str) -> str:
+    """
+    Normalize tmux session name (strip window/pane suffixes).
+
+    Examples:
+      "session:0" -> "session"
+      "session:window.pane" -> "session"
+    """
+    # Split on : to remove window/pane references
+    return name.split(":")[0]
+
+
+async def tmux_manager_hook(
+    tool_name: str, tool_input: Dict[str, Any], tool_output: Optional[str] = None
+) -> Optional[str]:
+    """
+    Post-tool-call hook that tracks tmux sessions.
+
+    Monitors Bash tool for tmux commands and tracks session names.
+    """
+    # Only process Bash tool
+    if tool_name != "Bash":
+        return None
+
+    command = tool_input.get("command", "")
+    if not command or "tmux" not in command:
+        return None
+
+    # Parse session name from tmux command
+    session_name = parse_tmux_command(command)
+
+    if session_name:
+        # Track with Stravinsky prefix
+        if not session_name.startswith(SESSION_PREFIX):
+            session_name = SESSION_PREFIX + session_name
+
+        _tracked_sessions.add(session_name)
+        logger.info(f"[TmuxManager] Tracking tmux session: {session_name}")
+
+        # Append reminder about active sessions
+        if tool_output:
+            reminder = f"\n\n[TMUX SESSION] Active session tracked: {session_name}\n" \
+                       f"Cleanup on session end: kill-session -t {session_name}"
+            return tool_output + reminder
+
+    return tool_output
+
+
+def cleanup_tmux_sessions() -> List[str]:
+    """
+    Kill all tracked tmux sessions.
+
+    Returns list of killed session names.
+    """
+    killed = []
+
+    for session_name in _tracked_sessions:
+        try:
+            # Kill tmux session
+            subprocess.run(
+                ["tmux", "kill-session", "-t", session_name],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=5
+            )
+            killed.append(session_name)
+            logger.info(f"[TmuxManager] Killed tmux session: {session_name}")
+
+        except FileNotFoundError:
+            logger.warning("[TmuxManager] tmux command not found")
+            break
+        except subprocess.TimeoutExpired:
+            logger.warning(f"[TmuxManager] Timeout killing session: {session_name}")
+        except Exception as e:
+            logger.error(f"[TmuxManager] Failed to kill session {session_name}: {e}")
+
+    # Clear tracked sessions
+    _tracked_sessions.clear()
+
+    return killed
+
+
+def get_tracked_sessions() -> Set[str]:
+    """
+    Get set of currently tracked tmux sessions.
+    """
+    return _tracked_sessions.copy()