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

mcp_bridge/hooks/HOOKS_SETTINGS.json

@@ -0,0 +1,175 @@
+{
+  "description": "Stravinsky MCP Hooks Configuration - Copy this to .claude/settings.json",
+  "installation_note": "These hooks are bundled with the stravinsky PyPI package. Hook paths should point to the installed package location or .claude/hooks/ if copied locally.",
+  
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/notification_hook.py",
+            "description": "Agent spawn notification messages"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/subagent_stop.py",
+            "description": "Agent completion handling and validation"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/pre_compact.py",
+            "description": "Context preservation before compaction"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read,Search,Grep,Bash,Edit,MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/stravinsky_mode.py",
+            "description": "Hard blocking of direct tools in stravinsky mode"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/parallel_execution.py",
+            "description": "Pre-emptive parallel execution enforcement"
+          },
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/context.py",
+            "description": "Auto-inject project context (CLAUDE.md, README.md)"
+          },
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/todo_continuation.py",
+            "description": "Remind about incomplete todos"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/truncator.py",
+            "description": "Truncate long tool responses"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__stravinsky__*,mcp__grep-app__*,Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/tool_messaging.py",
+            "description": "User-friendly MCP tool messaging"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit,MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/edit_recovery.py",
+            "description": "Recovery guidance for failed Edit operations"
+          }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ~/.claude/hooks/todo_delegation.py",
+            "description": "Parallel execution enforcer after TodoWrite"
+          }
+        ]
+      }
+    ]
+  },
+  
+  "usage_instructions": {
+    "installation": [
+      "1. Copy this file to .claude/settings.json in your project root",
+      "2. Ensure hook scripts are available at .claude/hooks/ (copy from package or use symlink)",
+      "3. Restart Claude Code or run /reload"
+    ],
+    "hook_paths": {
+      "local_copy": "Copy hooks to .claude/hooks/ and use relative paths (as shown above)",
+      "package_install": "Use absolute paths to installed package: python -c 'import mcp_bridge; print(mcp_bridge.__path__[0])'/hooks/",
+      "development": "For development, symlink: ln -s /path/to/stravinsky/mcp_bridge/hooks .claude/hooks"
+    },
+    "customization": [
+      "Disable individual hooks by removing them from the hooks array",
+      "Adjust matchers to change which tools trigger hooks",
+      "Add custom hooks by creating new Python scripts"
+    ]
+  },
+  
+  "hook_overview": {
+    "execution_control": {
+      "parallel_execution.py": "Detects implementation tasks and injects parallel execution instructions before response generation. Activates stravinsky mode on /stravinsky invocation.",
+      "stravinsky_mode.py": "Blocks native file tools (Read, Grep, Bash, Edit) when stravinsky mode is active, forcing Task delegation.",
+      "todo_delegation.py": "Hard blocks response completion after TodoWrite if 2+ pending items exist without spawning Task agents."
+    },
+    "context_management": {
+      "context.py": "Auto-injects CLAUDE.md, README.md, or AGENTS.md content into prompts for project-specific context.",
+      "todo_continuation.py": "Reminds about incomplete in_progress or pending todos before starting new work.",
+      "pre_compact.py": "Preserves critical context patterns (ARCHITECTURE, DESIGN DECISION, etc.) before compaction."
+    },
+    "tool_enhancement": {
+      "tool_messaging.py": "Outputs user-friendly messages about which agent/tool was used (e.g., 'delphi:gpt-5.2-medium(\"Analyzing architecture\")').",
+      "edit_recovery.py": "Detects Edit tool failures and suggests recovery actions (re-read file, verify exact match).",
+      "truncator.py": "Truncates tool responses longer than 30k characters to prevent token overflow."
+    },
+    "agent_lifecycle": {
+      "notification_hook.py": "Outputs spawn messages for agent delegation (e.g., 'spawned explore:gemini-3-flash(\"Find auth code\")').",
+      "subagent_stop.py": "Handles subagent completion, validates output, and can block if critical agents fail."
+    }
+  },
+  
+  "exit_code_reference": {
+    "0": "Success - Allow continuation",
+    "1": "Warning - Show message but continue",
+    "2": "Block - Hard failure (prevents tool execution in PreToolUse, or signals error in PostToolUse)"
+  },
+  
+  "state_files": {
+    "~/.stravinsky_mode": "Marker file indicating stravinsky orchestrator mode is active (enables hard blocking)",
+    "~/.claude/state/compaction.jsonl": "Audit log of context compaction events with preserved items",
+    ".claude/todo_state.json": "Cached todo state for continuation enforcement"
+  },
+  
+  "version": "0.2.63",
+  "package": "stravinsky",
+  "documentation": "https://github.com/GratefulDave/stravinsky"
+}

mcp_bridge/hooks/README.md

@@ -0,0 +1,215 @@
+# Stravinsky Hooks for Claude Code
+
+This directory contains 11 production-ready hooks that integrate with Claude Code to enforce parallel execution, stravinsky mode, and advanced workflow patterns.
+
+## Quick Start
+
+### Option 1: Copy to Local Project
+
+```bash
+# In your Claude Code project root
+mkdir -p .claude/hooks
+cp -r $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks/*.py .claude/hooks/
+cp $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks/HOOKS_SETTINGS.json .claude/settings.json
+```
+
+### Option 2: Symlink (Development)
+
+```bash
+# In your Claude Code project root
+mkdir -p .claude
+ln -s $(python -c "import mcp_bridge; print(mcp_bridge.__path__[0])")/hooks .claude/hooks
+cp .claude/hooks/HOOKS_SETTINGS.json .claude/settings.json
+```
+
+## Hook Files (11 Total)
+
+### Core Execution (3)
+1. **parallel_execution.py** - UserPromptSubmit hook
+   - Detects implementation tasks and injects parallel execution instructions
+   - Activates stravinsky mode when `/stravinsky` is invoked
+   - Creates `~/.stravinsky_mode` marker file for hard blocking
+
+2. **stravinsky_mode.py** - PreToolUse hook
+   - Blocks Read, Grep, Bash, Edit, MultiEdit when stravinsky mode is active
+   - Forces delegation via Task tool instead
+   - Exit code 2 = hard block
+
+3. **todo_delegation.py** - PostToolUse hook (after TodoWrite)
+   - Enforces parallel Task spawning when 2+ pending todos exist
+   - Blocks continuation without Task delegation in stravinsky mode
+   - Exit code 2 = hard block if stravinsky mode active
+
+### Context Management (3)
+4. **context.py** - UserPromptSubmit hook
+   - Auto-injects CLAUDE.md, README.md, or AGENTS.md content
+   - Prepends project context to every prompt
+   - Reduces need for explicit context requests
+
+5. **todo_continuation.py** - UserPromptSubmit hook
+   - Reminds about in_progress and pending todos
+   - Prevents starting new work when existing todos are incomplete
+   - Uses `.claude/todo_state.json` cache
+
+6. **pre_compact.py** - PreCompact hook
+   - Preserves critical context before compaction (ARCHITECTURE, DESIGN DECISION, etc.)
+   - Logs compaction events to `~/.claude/state/compaction.jsonl`
+   - Maintains stravinsky mode state across compactions
+
+### Tool Enhancement (3)
+7. **tool_messaging.py** - PostToolUse hook
+   - User-friendly messages for MCP tools and Task delegations
+   - Format: `🎯 delphi:gpt-5.2-medium('Strategic analysis')`
+   - Works with mcp__stravinsky__* and mcp__grep-app__* tools
+
+8. **edit_recovery.py** - PostToolUse hook (after Edit/MultiEdit)
+   - Detects Edit failures (oldString not found, multiple matches, etc.)
+   - Suggests recovery: re-read file, verify exact match
+   - Appends recovery guidance to error messages
+
+9. **truncator.py** - PostToolUse hook (all tools)
+   - Truncates responses longer than 30k characters
+   - Prevents token overflow and context bloat
+   - Adds truncation markers for transparency
+
+### Agent Lifecycle (2)
+10. **notification_hook.py** - Notification hook
+    - Outputs spawn messages for agent delegations
+    - Format: `spawned explore:gemini-3-flash('Find auth code')`
+    - Maps agents to their display models
+
+11. **subagent_stop.py** - SubagentStop hook
+    - Handles subagent completion events
+    - Validates output and detects failures
+    - Can block completion for critical agents (delphi, code-reviewer, debugger)
+
+## Configuration
+
+The `HOOKS_SETTINGS.json` file contains the complete hook configuration for `.claude/settings.json`. It includes:
+
+- Hook type mappings (UserPromptSubmit, PreToolUse, PostToolUse, etc.)
+- Tool matchers (which tools trigger which hooks)
+- Command paths (python3 .claude/hooks/hookname.py)
+- Descriptions for each hook
+
+## Hook Types & Exit Codes
+
+### Hook Types
+- **UserPromptSubmit**: Before response generation (can modify prompt)
+- **PreToolUse**: Before tool execution (can block with exit 2)
+- **PostToolUse**: After tool execution (can modify response)
+- **Notification**: On notification events
+- **SubagentStop**: When subagent completes
+- **PreCompact**: Before context compaction
+
+### Exit Codes
+- `0` - Success (allow continuation)
+- `1` - Warning (show message but continue)
+- `2` - Block/Error (prevents tool in PreToolUse, signals failure in PostToolUse)
+
+## State Files
+
+Hooks use these state files:
+
+| File | Purpose |
+|------|---------|
+| `~/.stravinsky_mode` | Marker for stravinsky orchestrator mode (enables hard blocking) |
+| `~/.claude/state/compaction.jsonl` | Audit log of context compaction events |
+| `.claude/todo_state.json` | Cached todo state for continuation enforcement |
+
+## Testing Hooks
+
+Test individual hooks with JSON input:
+
+```bash
+# Test parallel_execution
+echo '{"prompt": "implement feature X"}' | python3 parallel_execution.py
+
+# Test stravinsky_mode (should block)
+touch ~/.stravinsky_mode
+echo '{"toolName": "Read", "params": {}}' | python3 stravinsky_mode.py
+echo $?  # Should be 2
+
+# Test todo_delegation
+echo '{"tool_name": "TodoWrite", "tool_input": {"todos": [{"status": "pending"}, {"status": "pending"}]}}' | python3 todo_delegation.py
+```
+
+## Customization
+
+To disable a hook:
+1. Open `.claude/settings.json`
+2. Find the hook in the hooks array
+3. Remove or comment out the hook object
+
+To modify a hook:
+1. Copy the hook file to your project's `.claude/hooks/`
+2. Edit as needed
+3. Update the command path in `.claude/settings.json`
+
+## Environment Variables
+
+Hooks receive these from Claude Code:
+- `CLAUDE_CWD` - Current working directory
+- `CLAUDE_TOOL_NAME` - Tool being invoked
+- `CLAUDE_SESSION_ID` - Active session ID
+
+## Workflow
+
+### Stravinsky Mode Flow
+1. User invokes `/stravinsky`
+2. `parallel_execution.py` detects it and creates `~/.stravinsky_mode`
+3. `stravinsky_mode.py` now blocks Read/Grep/Bash/Edit tools
+4. Claude must use Task tool for delegation
+5. `todo_delegation.py` enforces parallel Task spawning for 2+ pending todos
+
+### Normal Flow (No Stravinsky Mode)
+1. User submits prompt
+2. `context.py` injects CLAUDE.md content
+3. `todo_continuation.py` reminds about incomplete todos
+4. `parallel_execution.py` adds parallel execution guidance if implementation task
+5. Claude generates response
+6. `tool_messaging.py` outputs friendly tool messages
+7. `truncator.py` truncates long responses
+
+## Troubleshooting
+
+### Hooks Not Firing
+- Check `.claude/settings.json` exists with hook configuration
+- Verify hook scripts are executable: `chmod +x .claude/hooks/*.py`
+- Check hook paths are correct (relative to project root)
+- Restart Claude Code: `/reload`
+
+### Stravinsky Mode Stuck Active
+- Remove marker file: `rm ~/.stravinsky_mode`
+- Check for orphaned mode files: `ls -la ~/ | grep stravinsky`
+
+### Hooks Causing Errors
+- Test hooks individually (see Testing section above)
+- Check Python version: `python3 --version` (requires 3.8+)
+- Review hook stderr output in Claude Code logs
+- Disable problematic hooks temporarily
+
+## Integration with Stravinsky MCP
+
+These hooks are designed to work seamlessly with the Stravinsky MCP server:
+
+- `tool_messaging.py` recognizes `mcp__stravinsky__*` tools
+- `parallel_execution.py` works with `agent_spawn` MCP tool
+- `stravinsky_mode.py` forces use of MCP Task delegation
+- All hooks respect the parallel execution philosophy
+
+## Version
+
+Version: 0.2.61
+Package: stravinsky
+Repository: https://github.com/GratefulDave/stravinsky
+
+## License
+
+MIT License - See package LICENSE file
+
+## Support
+
+For issues or questions:
+- GitHub Issues: https://github.com/GratefulDave/stravinsky/issues
+- Documentation: See CLAUDE.md in package root

mcp_bridge/hooks/__init__.py

@@ -1,49 +1,125 @@
 """
-Hooks initialization.
-Registers all Tier 1-4 hooks into the HookManager.
+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
+__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)
-
-    # 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)
-
-    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()