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

mcp_bridge/hooks/__init__.py

@@ -1,66 +1,125 @@
 """
-Hooks initialization.
-Registers all Tier 1-5 hooks into the HookManager.
-
-Hook Tiers:
-- Tier 1: Post-tool-call (immediate response modification)
-- Tier 2: Pre-model-invoke (context management)
-- Tier 3: Pre-model-invoke (performance optimization)
-- Tier 4: Pre-model-invoke (behavior enforcement)
-- Tier 5: Session lifecycle (idle detection, compaction)
+Stravinsky Hooks - Claude Code Integration
+
+This package contains all hook files for deep integration with Claude Code.
+Hooks are Python scripts that intercept Claude Code events to enforce
+parallel execution, stravinsky mode, and other workflow patterns.
+
+## Available Hooks
+
+### Core Execution Hooks
+- `parallel_execution.py` - UserPromptSubmit: Pre-emptive parallel execution enforcement
+- `stravinsky_mode.py` - PreToolUse: Hard blocking of direct tools (Read, Grep, Bash)
+- `todo_delegation.py` - PostToolUse: Parallel execution enforcer after TodoWrite
+
+### Context & State Hooks
+- `context.py` - UserPromptSubmit: Auto-inject project context (CLAUDE.md, README.md)
+- `todo_continuation.py` - UserPromptSubmit: Remind about incomplete todos
+- `pre_compact.py` - PreCompact: Context preservation before compaction
+
+### Tool Enhancement Hooks
+- `tool_messaging.py` - PostToolUse: User-friendly tool/agent messaging
+- `edit_recovery.py` - PostToolUse: Recovery guidance for failed Edit operations
+- `truncator.py` - PostToolUse: Truncate long tool responses to prevent token overflow
+
+### Agent Lifecycle Hooks
+- `notification_hook.py` - Notification: Agent spawn messages
+- `subagent_stop.py` - SubagentStop: Agent completion handling
+
+## Installation for Claude Code
+
+Copy the HOOKS_SETTINGS.json configuration to your project's .claude/settings.json:
+
+```bash
+# From PyPI package location
+cp $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks/HOOKS_SETTINGS.json .claude/settings.json
+```
+
+Or manually configure in .claude/settings.json (see HOOKS_SETTINGS.json for template).
+
+## Hook Types
+
+Claude Code supports these hook types:
+- **UserPromptSubmit**: Fires before response generation
+- **PreToolUse**: Fires before tool execution (can block with exit 2)
+- **PostToolUse**: Fires after tool execution
+- **Notification**: Fires on notification events
+- **SubagentStop**: Fires when subagent completes
+- **PreCompact**: Fires before context compaction
+
+## Exit Codes
+
+- `0` - Success (allow continuation)
+- `1` - Warning (show but continue)
+- `2` - Block (hard failure in stravinsky mode)
+
+## Environment Variables
+
+Hooks receive these environment variables from Claude Code:
+- `CLAUDE_CWD` - Current working directory
+- `CLAUDE_TOOL_NAME` - Tool being invoked (PreToolUse/PostToolUse)
+- `CLAUDE_SESSION_ID` - Active session ID
+
+## State Management
+
+Stravinsky mode uses a marker file for state:
+- `~/.stravinsky_mode` - Active when file exists
+- Created by `/stravinsky` skill invocation
+- Enables hard blocking of direct tools
+
+## Usage
+
+These hooks are automatically installed with the Stravinsky MCP package.
+To enable them in a Claude Code project:
+
+1. Copy HOOKS_SETTINGS.json to .claude/settings.json
+2. Adjust hook paths if needed (default assumes installed via PyPI)
+3. Restart Claude Code or reload configuration
+
+## Development
+
+To test hooks locally:
+
+```bash
+# Test parallel_execution hook
+echo '{"prompt": "implement feature X"}' | python parallel_execution.py
+
+# Test stravinsky_mode hook (requires marker file)
+touch ~/.stravinsky_mode
+echo '{"toolName": "Read", "params": {}}' | python stravinsky_mode.py
+echo $?  # Should be 2 (blocked)
+rm ~/.stravinsky_mode
+```
+
+## Package Contents
 """
 
-from .manager import get_hook_manager
-from .truncator import output_truncator_hook
-from .edit_recovery import edit_error_recovery_hook
-from .directory_context import directory_context_hook
-from .compaction import context_compaction_hook
-from .budget_optimizer import budget_optimizer_hook
-from .todo_enforcer import todo_continuation_hook
-from .keyword_detector import keyword_detector_hook
-from .comment_checker import comment_checker_hook
-from .context_monitor import context_monitor_hook
-from .agent_reminder import agent_reminder_hook
-from .preemptive_compaction import preemptive_compaction_hook
-from .auto_slash_command import auto_slash_command_hook
-from .session_recovery import session_recovery_hook
-from .empty_message_sanitizer import empty_message_sanitizer_hook
-
-# New hooks based on oh-my-opencode patterns
-from .session_idle import session_idle_hook
-from .pre_compact import pre_compact_hook
-from .parallel_enforcer import parallel_enforcer_post_tool_hook
+__all__ = [
+    # Core execution
+    "parallel_execution",
+    "stravinsky_mode",
+    "todo_delegation",
+    # Context & state
+    "context",
+    "todo_continuation",
+    "pre_compact",
+    # Tool enhancement
+    "tool_messaging",
+    "edit_recovery",
+    "truncator",
+    # Agent lifecycle
+    "notification_hook",
+    "subagent_stop",
+]
 
 
 def initialize_hooks():
-    """Register all available hooks."""
-    manager = get_hook_manager()
-
-    # Tier 1: Post-tool-call (immediate response modification)
-    manager.register_post_tool_call(output_truncator_hook)
-    manager.register_post_tool_call(edit_error_recovery_hook)
-    manager.register_post_tool_call(comment_checker_hook)
-    manager.register_post_tool_call(agent_reminder_hook)
-    manager.register_post_tool_call(session_recovery_hook)
-    manager.register_post_tool_call(parallel_enforcer_post_tool_hook)  # NEW: Enforce parallel spawning
-
-    # Tier 2: Pre-model-invoke (context management)
-    manager.register_pre_model_invoke(directory_context_hook)
-    manager.register_pre_model_invoke(context_compaction_hook)
-    manager.register_pre_model_invoke(context_monitor_hook)
-    manager.register_pre_model_invoke(preemptive_compaction_hook)
-    manager.register_pre_model_invoke(empty_message_sanitizer_hook)
-
-    # Tier 3: Pre-model-invoke (performance optimization)
-    manager.register_pre_model_invoke(budget_optimizer_hook)
-
-    # Tier 4: Pre-model-invoke (behavior enforcement)
-    manager.register_pre_model_invoke(keyword_detector_hook)
-    manager.register_pre_model_invoke(todo_continuation_hook)
-    manager.register_pre_model_invoke(auto_slash_command_hook)
-
-    # Tier 5: Session lifecycle hooks (NEW)
-    manager.register_session_idle(session_idle_hook)  # Stop hook - idle detection
-    manager.register_pre_compact(pre_compact_hook)    # PreCompact - context preservation
-
-    return manager
+    """Initialize and register all hooks with the HookManager."""
+    # Currently hooks are primarily external scripts or lazy-loaded.
+    # This entry point allows for future internal hook registration.
+    pass
+
+
+__version__ = "0.2.63"
+__author__ = "David Andrews"
+__description__ = "Claude Code hooks for Stravinsky MCP parallel execution"

mcp_bridge/hooks/edit_recovery.py

@@ -1,41 +1,46 @@
-"""
-Edit error recovery hook.
-Detects common mistakes in file editing and injects high-priority corrective directives.
-"""
-
+import os
+import sys
+import json
 import re
-from typing import Any, Dict, Optional
 
-EDIT_ERROR_PATTERNS = [
-    r"oldString and newString must be different",
-    r"oldString not found",
-    r"oldString found multiple times",
-    r"Target content not found",
-    r"Multiple occurrences of target content found",
-]
+def main():
+    # Claude Code PostToolUse inputs via Environment Variables
+    tool_name = os.environ.get("CLAUDE_TOOL_NAME")
+    
+    # We only care about Edit/MultiEdit
+    if tool_name not in ["Edit", "MultiEdit"]:
+        return
 
-EDIT_RECOVERY_PROMPT = """
-> **[EDIT ERROR - IMMEDIATE ACTION REQUIRED]**
-> You made an Edit mistake. STOP and do this NOW:
-> 1. **READ** the file immediately to see its ACTUAL current state.
-> 2. **VERIFY** what the content really looks like (your assumption was wrong).
-> 3. **APOLOGIZE** briefly to the user for the error.
-> 4. **CONTINUE** with corrected action based on the real file content.
-> **DO NOT** attempt another edit until you've read and verified the file state.
-"""
+    # Read from stdin (Claude Code passes the tool response via stdin for some hook types, 
+    # but for PostToolUse it's often better to check the environment variable if available.
+    # Actually, the summary says input is a JSON payload.
+    try:
+        data = json.load(sys.stdin)
+        tool_response = data.get("tool_response", "")
+    except Exception:
+        # Fallback to direct string if not JSON
+        return
 
-async def edit_error_recovery_hook(tool_name: str, arguments: Dict[str, Any], output: str) -> Optional[str]:
-    """
-    Analyzes tool output for edit errors and appends corrective directives.
-    """
-    # Check if this is an edit-related tool (handling both built-in and common MCP tools)
-    edit_tools = ["replace_file_content", "multi_replace_file_content", "write_to_file", "edit_file", "Edit"]
-    
-    # We also check the output content for common patterns even if the tool name doesn't match perfectly
-    is_edit_error = any(re.search(pattern, output, re.IGNORECASE) for pattern in EDIT_ERROR_PATTERNS)
-    
-    if is_edit_error or any(tool in tool_name for tool in edit_tools):
-        if any(re.search(pattern, output, re.IGNORECASE) for pattern in EDIT_ERROR_PATTERNS):
-            return output + EDIT_RECOVERY_PROMPT
-            
-    return None
+    # Error patterns
+    error_patterns = [
+        r"oldString not found",
+        r"oldString matched multiple times",
+        r"line numbers out of range"
+    ]
+
+    recovery_needed = any(re.search(p, tool_response, re.IGNORECASE) for p in error_patterns)
+
+    if recovery_needed:
+        correction = (
+            "\n\n[SYSTEM RECOVERY] It appears the Edit tool failed to find the target string. "
+            "Please call 'Read' on the file again to verify the current content, "
+            "then ensure your 'oldString' is an EXACT match including all whitespace."
+        )
+        # For PostToolUse, stdout is captured and appended/replaces output
+        print(tool_response + correction)
+    else:
+        # No change
+        print(tool_response)
+
+if __name__ == "__main__":
+    main()

mcp_bridge/hooks/git_noninteractive.py

@@ -0,0 +1,89 @@
+"""
+Git Non-Interactive Environment Hook.
+
+Prevents git interactive command hangs by prepending environment variables.
+"""
+
+import logging
+import re
+import shlex
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Patterns for banned interactive git commands
+BANNED_INTERACTIVE_PATTERNS = [
+    r"git\s+add\s+.*-p",  # git add -p (patch mode)
+    r"git\s+add\s+.*--patch",
+    r"git\s+commit\s+.*-v",  # git commit -v (verbose with diff)
+    r"git\s+rebase\s+.*-i",  # git rebase -i (interactive)
+    r"git\s+rebase\s+.*--interactive",
+    r"git\s+add\s+.*-i",  # git add -i (interactive)
+    r"git\s+add\s+.*--interactive",
+    r"git\s+checkout\s+.*-p",  # git checkout -p (patch mode)
+    r"git\s+reset\s+.*-p",  # git reset -p (patch mode)
+]
+
+# Environment variables to set for non-interactive git
+NON_INTERACTIVE_ENV = {
+    "GIT_TERMINAL_PROMPT": "0",
+    "GIT_EDITOR": "true",  # No-op editor
+    "GIT_PAGER": "cat",  # No paging
+}
+
+
+def escape_shell_arg(arg: str) -> str:
+    """
+    Escape shell argument for safe injection.
+    """
+    # Use shlex.quote for proper escaping
+    return shlex.quote(arg)
+
+
+async def git_noninteractive_hook(
+    tool_name: str, arguments: Dict[str, Any]
+) -> Optional[Dict[str, Any]]:
+    """
+    Pre-tool-call hook that prepends non-interactive env vars to git commands.
+
+    Detects interactive git commands and either:
+    1. Warns and blocks them (if highly interactive like -i)
+    2. Prepends env vars to make them non-interactive
+    """
+    # Only process Bash tool
+    if tool_name != "Bash":
+        return None
+
+    command = arguments.get("command", "")
+    if not command or "git" not in command.lower():
+        return None
+
+    # Check for banned interactive patterns
+    for pattern in BANNED_INTERACTIVE_PATTERNS:
+        if re.search(pattern, command, re.IGNORECASE):
+            logger.warning(
+                f"[GitNonInteractive] Detected interactive git command: {pattern}"
+            )
+            # Add warning to command output
+            warning = (
+                f"\n[WARNING] Interactive git command detected: {command}\n"
+                f"This may hang. Consider using non-interactive alternatives.\n"
+            )
+            # Don't block, just warn - user might know what they're doing
+            return None
+
+    # Prepend environment variables to make git non-interactive
+    if "git" in command.lower():
+        env_prefix = " ".join(
+            [f"{k}={escape_shell_arg(v)}" for k, v in NON_INTERACTIVE_ENV.items()]
+        )
+        modified_command = f"{env_prefix} {command}"
+
+        logger.info(f"[GitNonInteractive] Prepending non-interactive env vars to git command")
+
+        # Return modified arguments
+        modified_args = arguments.copy()
+        modified_args["command"] = modified_command
+        return modified_args
+
+    return None

mcp_bridge/hooks/keyword_detector.py

@@ -84,11 +84,41 @@ IF COMPLEX (architecture, multi-system, debugging after 2+ failures):
 SYNTHESIZE findings before proceeding.
 """
 
+ULTRATHINK_MODE = """[ultrathink-mode]
+ENGAGE MAXIMUM REASONING CAPACITY.
+
+Extended thinking mode activated with 32k token thinking budget.
+This enables exhaustive deep reasoning and multi-dimensional analysis.
+
+## REASONING PRINCIPLES
+- **Deep Analysis**: Consider edge cases, security implications, performance impacts
+- **Multi-Perspective**: Analyze from user, developer, system, and security viewpoints
+- **Strategic Planning**: Consult delphi agent for architecture decisions and hard problems
+- **Root Cause**: Don't treat symptoms - identify and address underlying causes
+- **Risk Assessment**: Evaluate trade-offs, failure modes, and mitigation strategies
+
+## THINKING WORKFLOW
+1. Problem decomposition into atomic components
+2. Parallel exploration of solution space (spawn agents for research)
+3. Consult delphi for strategic guidance on complex decisions
+4. Multi-dimensional trade-off analysis
+5. Solution synthesis with verification plan
+
+## VERIFICATION
+- Test assumptions against reality
+- Challenge your own reasoning
+- Seek disconfirming evidence
+- Consider second-order effects
+
+Use delphi agent for strategic consultation on architecture, debugging, and complex trade-offs.
+"""
+
 KEYWORD_PATTERNS = {
     r"\bironstar\b": IRONSTAR_MODE,
     r"\birs\b": IRONSTAR_MODE,
     r"\bultrawork\b": IRONSTAR_MODE,
     r"\bulw\b": IRONSTAR_MODE,
+    r"\bultrathink\b": ULTRATHINK_MODE,
     r"\bsearch\b": SEARCH_MODE,
     r"\banalyze\b": ANALYZE_MODE,
     r"\banalysis\b": ANALYZE_MODE,

mcp_bridge/hooks/manager.py

@@ -6,6 +6,14 @@ Provides interception points for tool calls and model invocations.
 import logging
 from typing import Any, Callable, Dict, List, Optional, Awaitable
 
+try:
+    from mcp_bridge.config.hook_config import is_hook_enabled
+except ImportError:
+
+    def is_hook_enabled(hook_name: str) -> bool:
+        return True
+
+
 logger = logging.getLogger(__name__)
 
 

mcp_bridge/hooks/notification_hook.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+"""
+Notification hook for agent spawn messages.
+
+Fires on Notification events to output user-friendly messages about
+which agent was spawned, what model it uses, and what task it's doing.
+
+Format: spawned {agent_type}:{model}('{description}')
+Example: spawned delphi:gpt-5.2-medium('Debug xyz code')
+"""
+
+import json
+import sys
+from typing import Optional, Dict, Any
+
+
+# Agent display model mappings
+AGENT_DISPLAY_MODELS = {
+    "explore": "gemini-3-flash",
+    "dewey": "gemini-3-flash",
+    "document_writer": "gemini-3-flash",
+    "multimodal": "gemini-3-flash",
+    "frontend": "gemini-3-pro-high",
+    "delphi": "gpt-5.2-medium",
+    "planner": "opus-4.5",
+    "code-reviewer": "sonnet-4.5",
+    "debugger": "sonnet-4.5",
+    "_default": "sonnet-4.5",
+}
+
+
+def extract_agent_info(message: str) -> Optional[Dict[str, str]]:
+    """
+    Extract agent spawn information from notification message.
+
+    Looks for patterns like:
+    - "Agent explore spawned for task..."
+    - "Spawned delphi agent: description"
+    - Task tool delegation messages
+    """
+    message_lower = message.lower()
+
+    # Try to extract agent type from message
+    agent_type = None
+    description = ""
+
+    for agent in AGENT_DISPLAY_MODELS.keys():
+        if agent == "_default":
+            continue
+        if agent in message_lower:
+            agent_type = agent
+            # Extract description after agent name
+            idx = message_lower.find(agent)
+            description = message[idx + len(agent):].strip()[:60]
+            break
+
+    if not agent_type:
+        return None
+
+    # Clean up description
+    description = description.strip(":-() ")
+    if not description:
+        description = "task delegated"
+
+    display_model = AGENT_DISPLAY_MODELS.get(agent_type, AGENT_DISPLAY_MODELS["_default"])
+
+    return {
+        "agent_type": agent_type,
+        "model": display_model,
+        "description": description,
+    }
+
+
+def main():
+    """Main hook entry point."""
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        return 0
+
+    # Get notification message
+    message = hook_input.get("message", "")
+    notification_type = hook_input.get("notification_type", "")
+
+    # Only process agent-related notifications
+    agent_keywords = ["agent", "spawn", "delegat", "task"]
+    if not any(kw in message.lower() for kw in agent_keywords):
+        return 0
+
+    # Extract agent info
+    agent_info = extract_agent_info(message)
+    if not agent_info:
+        return 0
+
+    # Format and output
+    output = f"spawned {agent_info['agent_type']}:{agent_info['model']}('{agent_info['description']}')"
+    print(output, file=sys.stderr)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mcp_bridge/hooks/parallel_execution.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook: Pre-emptive parallel execution enforcement.
+
+Fires BEFORE response generation to inject parallel execution instructions
+when implementation tasks are detected. Eliminates timing ambiguity.
+
+CRITICAL: Also activates stravinsky mode marker when /stravinsky is invoked,
+enabling hard blocking of direct tools (Read, Grep, Bash) via stravinsky_mode.py.
+"""
+import json
+import sys
+import re
+from pathlib import Path
+
+# Marker file that enables hard blocking of direct tools
+STRAVINSKY_MODE_FILE = Path.home() / ".stravinsky_mode"
+
+
+def detect_stravinsky_invocation(prompt):
+    """Detect if /stravinsky skill is being invoked."""
+    patterns = [
+        r'/stravinsky',
+        r'<command-name>/stravinsky</command-name>',
+        r'stravinsky orchestrator',
+        r'ultrawork',
+        r'ultrathink',
+    ]
+    prompt_lower = prompt.lower()
+    return any(re.search(p, prompt_lower) for p in patterns)
+
+
+def activate_stravinsky_mode():
+    """Create marker file to enable hard blocking of direct tools."""
+    try:
+        config = {"active": True, "reason": "invoked via /stravinsky skill"}
+        STRAVINSKY_MODE_FILE.write_text(json.dumps(config))
+        return True
+    except IOError:
+        return False
+
+
+def detect_implementation_task(prompt):
+    """Detect if prompt is an implementation task requiring parallel execution."""
+    keywords = [
+        'implement', 'add', 'create', 'build', 'refactor', 'fix',
+        'update', 'modify', 'change', 'develop', 'write code',
+        'feature', 'bug fix', 'enhancement', 'integrate'
+    ]
+
+    prompt_lower = prompt.lower()
+    return any(kw in prompt_lower for kw in keywords)
+
+
+def main():
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        return 0
+
+    prompt = hook_input.get("prompt", "")
+
+    # CRITICAL: Activate stravinsky mode if /stravinsky is invoked
+    # This creates the marker file that enables hard blocking of direct tools
+    is_stravinsky = detect_stravinsky_invocation(prompt)
+    if is_stravinsky:
+        activate_stravinsky_mode()
+
+    # Only inject for implementation tasks OR stravinsky invocation
+    if not detect_implementation_task(prompt) and not is_stravinsky:
+        print(prompt)
+        return 0
+
+    # Inject parallel execution instruction BEFORE prompt
+    instruction = """
+[🔄 PARALLEL EXECUTION MODE ACTIVE]
+
+When you create a TodoWrite with 2+ pending items:
+
+✅ IMMEDIATELY in THIS SAME RESPONSE (do NOT end response after TodoWrite):
+   1. Spawn Task() for EACH independent pending TODO
+   2. Use: Task(subagent_type="explore"|"Plan"|etc., prompt="...", description="...", run_in_background=true)
+   3. Fire ALL Task calls in ONE response block
+   4. Do NOT mark any TODO as in_progress until Task results return
+
+❌ DO NOT:
+   - End your response after TodoWrite
+   - Mark TODOs in_progress before spawning Tasks
+   - Spawn only ONE Task (spawn ALL independent tasks)
+   - Wait for "next response" to spawn Tasks
+
+Example pattern (all in SAME response):
+```
+TodoWrite([task1, task2, task3])
+Task(subagent_type="Explore", prompt="Task 1 details", description="Task 1", run_in_background=true)
+Task(subagent_type="Plan", prompt="Task 2 details", description="Task 2", run_in_background=true)
+Task(subagent_type="Explore", prompt="Task 3 details", description="Task 3", run_in_background=true)
+# Continue response - collect results with TaskOutput
+```
+
+---
+
+"""
+
+    modified_prompt = instruction + prompt
+    print(modified_prompt)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())