stravinsky 0.2.52__py3-none-any.whl → 0.2.67__py3-none-any.whl

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()

mcp_bridge/hooks/todo_continuation.py

@@ -0,0 +1,90 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook: Todo Continuation Enforcer
+
+Checks if there are incomplete todos (in_progress or pending) and injects
+a reminder to continue working on them before starting new work.
+
+Aligned with oh-my-opencode's [SYSTEM REMINDER - TODO CONTINUATION] pattern.
+"""
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def get_todo_state() -> dict:
+    """Try to get current todo state from Claude Code session or local cache."""
+    # Claude Code stores todo state - we can check via session files
+    # For now, we'll use a simple file-based approach
+    cwd = Path(os.environ.get("CLAUDE_CWD", "."))
+    todo_cache = cwd / ".claude" / "todo_state.json"
+
+    if todo_cache.exists():
+        try:
+            return json.loads(todo_cache.read_text())
+        except Exception:
+            pass
+
+    return {"todos": []}
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+        prompt = data.get("prompt", "")
+    except Exception:
+        return 0
+
+    # Get current todo state
+    state = get_todo_state()
+    todos = state.get("todos", [])
+
+    if not todos:
+        # No todos tracked, pass through
+        print(prompt)
+        return 0
+
+    # Count incomplete todos
+    in_progress = [t for t in todos if t.get("status") == "in_progress"]
+    pending = [t for t in todos if t.get("status") == "pending"]
+
+    if not in_progress and not pending:
+        # All todos complete, pass through
+        print(prompt)
+        return 0
+
+    # Build reminder
+    reminder_parts = ["[SYSTEM REMINDER - TODO CONTINUATION]", ""]
+
+    if in_progress:
+        reminder_parts.append(f"IN PROGRESS ({len(in_progress)} items):")
+        for t in in_progress:
+            reminder_parts.append(f"  - {t.get('content', 'Unknown task')}")
+        reminder_parts.append("")
+
+    if pending:
+        reminder_parts.append(f"PENDING ({len(pending)} items):")
+        for t in pending[:5]:  # Show max 5 pending
+            reminder_parts.append(f"  - {t.get('content', 'Unknown task')}")
+        if len(pending) > 5:
+            reminder_parts.append(f"  ... and {len(pending) - 5} more")
+        reminder_parts.append("")
+
+    reminder_parts.extend([
+        "IMPORTANT: You have incomplete work. Before starting anything new:",
+        "1. Continue working on IN_PROGRESS todos first",
+        "2. If blocked, explain why and move to next PENDING item",
+        "3. Only start NEW work if all todos are complete or explicitly abandoned",
+        "",
+        "---",
+        "",
+    ])
+
+    reminder = "\n".join(reminder_parts)
+    print(reminder + prompt)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_bridge/hooks/todo_delegation.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""
+PostToolUse hook for TodoWrite: CRITICAL parallel execution enforcer.
+
+This hook fires AFTER TodoWrite completes. If there are 2+ pending items,
+it outputs a STRONG reminder that Task agents must be spawned immediately.
+
+Exit code 2 is used to signal a HARD BLOCK - Claude should see this as
+a failure condition requiring immediate correction.
+
+Works in tandem with:
+- parallel_execution.py (UserPromptSubmit): Pre-emptive instruction injection
+- stravinsky_mode.py (PreToolUse): Hard blocking of Read/Grep/Bash tools
+"""
+import json
+import sys
+from pathlib import Path
+
+# Check if stravinsky mode is active (hard blocking enabled)
+STRAVINSKY_MODE_FILE = Path.home() / ".stravinsky_mode"
+
+
+def is_stravinsky_mode():
+    """Check if hard blocking mode is active."""
+    return STRAVINSKY_MODE_FILE.exists()
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        return 0
+
+    tool_name = hook_input.get("tool_name", "")
+
+    if tool_name != "TodoWrite":
+        return 0
+
+    # Get the todos that were just written
+    tool_input = hook_input.get("tool_input", {})
+    todos = tool_input.get("todos", [])
+
+    # Count pending todos
+    pending_count = sum(1 for t in todos if t.get("status") == "pending")
+
+    if pending_count < 2:
+        return 0
+
+    # Check if stravinsky mode is active
+    stravinsky_active = is_stravinsky_mode()
+
+    # CRITICAL: Output urgent reminder for parallel Task spawning
+    mode_warning = ""
+    if stravinsky_active:
+        mode_warning = """
+⚠️ STRAVINSKY MODE ACTIVE - Direct tools (Read, Grep, Bash) are BLOCKED.
+   You MUST use Task(subagent_type="explore", ...) for ALL file operations.
+"""
+
+    error_message = f"""
+🚨 PARALLEL DELEGATION REQUIRED 🚨
+
+TodoWrite created {pending_count} pending items.
+{mode_warning}
+You MUST spawn Task agents for ALL independent TODOs in THIS SAME RESPONSE.
+
+Required pattern (IMMEDIATELY after this message):
+Task(subagent_type="explore", prompt="TODO 1...", description="TODO 1", run_in_background=true)
+Task(subagent_type="explore", prompt="TODO 2...", description="TODO 2", run_in_background=true)
+...
+
+DO NOT:
+- End your response without spawning Tasks
+- Mark TODOs in_progress before spawning Tasks
+- Use Read/Grep/Bash directly (BLOCKED in stravinsky mode)
+
+Your NEXT action MUST be multiple Task() calls, one for each independent TODO.
+"""
+    print(error_message, file=sys.stderr)
+
+    # Exit code 2 = HARD BLOCK in stravinsky mode
+    # Exit code 1 = WARNING otherwise
+    return 2 if stravinsky_active else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())