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

mcp_bridge/hooks/directory_context.py

@@ -3,11 +3,11 @@ Directory context injector hook.
 Automatically finds and injects local AGENTS.md or README.md content based on the current context.
 """
 
-import os
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any
 
-async def directory_context_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+
+async def directory_context_hook(params: dict[str, Any]) -> dict[str, Any] | None:
     """
     Search for AGENTS.md or README.md in the current working directory and inject them.
     """

mcp_bridge/hooks/edit_recovery.py

@@ -1,7 +1,8 @@
-import os
-import sys
 import json
+import os
 import re
+import sys
+
 
 def main():
     # Claude Code PostToolUse inputs via Environment Variables

mcp_bridge/hooks/edit_recovery_policy.py

@@ -0,0 +1,49 @@
+import re
+
+from .events import EventType, HookPolicy, PolicyResult, ToolCallEvent
+
+
+class EditRecoveryPolicy(HookPolicy):
+    """
+    Policy to provide recovery guidance when Edit/MultiEdit tools fail.
+    """
+
+    @property
+    def event_type(self) -> EventType:
+        return EventType.POST_TOOL_CALL
+
+    async def evaluate(self, event: ToolCallEvent) -> PolicyResult:
+        if event.tool_name not in ["Edit", "MultiEdit", "replace"]:
+            return PolicyResult(modified_data=event.output)
+
+        if not event.output:
+            return PolicyResult(modified_data=event.output)
+
+        # Error patterns
+        error_patterns = [
+            r"oldString not found",
+            r"oldString matched multiple times",
+            r"line numbers out of range",
+            r"does not match exactly",
+            r"failed to find the target string",
+        ]
+
+        recovery_needed = any(re.search(p, event.output, 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."
+            )
+            return PolicyResult(
+                modified_data=event.output + correction,
+                message=correction,
+            )
+
+        return PolicyResult(modified_data=event.output)
+
+
+if __name__ == "__main__":
+    policy = EditRecoveryPolicy()
+    policy.run_as_native()

mcp_bridge/hooks/empty_message_sanitizer.py

@@ -10,7 +10,7 @@ Cleans up empty/malformed messages:
 
 import logging
 import re
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -181,7 +181,7 @@ def sanitize_message_blocks(prompt: str) -> tuple[str, int]:
     return prompt, sanitized_count
 
 
-async def empty_message_sanitizer_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+async def empty_message_sanitizer_hook(params: dict[str, Any]) -> dict[str, Any] | None:
     """
     Pre-model invoke hook that sanitizes empty and malformed message content.
 

mcp_bridge/hooks/events.py

@@ -0,0 +1,160 @@
+"""
+Unified Event Model and Policy Base for Stravinsky Hooks.
+Enables code sharing between native Claude Code hooks and MCP bridge hooks.
+"""
+
+import asyncio
+import json
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Optional
+
+
+class EventType(Enum):
+    PRE_TOOL_CALL = "pre_tool_call"
+    POST_TOOL_CALL = "post_tool_call"
+    PRE_MODEL_INVOKE = "pre_model_invoke"
+    SESSION_IDLE = "session_idle"
+    PRE_COMPACT = "pre_compact"
+    NOTIFICATION = "notification"
+    SUBAGENT_STOP = "subagent_stop"
+
+
+@dataclass
+class ToolCallEvent:
+    tool_name: str
+    arguments: dict[str, Any]
+    output: str | None = None
+    event_type: EventType = EventType.PRE_TOOL_CALL
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_mcp(
+        cls, tool_name: str, arguments: dict[str, Any], output: str | None = None
+    ) -> "ToolCallEvent":
+        event_type = EventType.POST_TOOL_CALL if output is not None else EventType.PRE_TOOL_CALL
+        return cls(tool_name=tool_name, arguments=arguments, output=output, event_type=event_type)
+
+    @classmethod
+    def from_native(cls) -> Optional["ToolCallEvent"]:
+        """Parses ToolCallEvent from stdin (Native Claude Code hook pattern)."""
+        try:
+            # Native hooks often get input via stdin
+            if sys.stdin.isatty():
+                return None
+
+            raw_input = sys.stdin.read()
+            if not raw_input:
+                return None
+
+            data = json.loads(raw_input)
+            # print(f"DEBUG: raw_data={data}", file=sys.stderr)
+
+            # Claude Code native hook input varies by type
+            tool_name = data.get("tool_name") or data.get("toolName", "")
+            arguments = data.get("tool_input") or data.get("params", {})
+            output = data.get("output") or data.get("tool_response")
+
+            # Infer event type from env or data
+            import os
+            native_type = os.environ.get("CLAUDE_HOOK_TYPE", "")
+
+            # print(f"DEBUG: native_type={native_type}, output={output}", file=sys.stderr)
+
+            event_type = EventType.PRE_TOOL_CALL
+            if "PostToolUse" in native_type or output is not None:
+                event_type = EventType.POST_TOOL_CALL
+            elif "PreCompact" in native_type:
+                event_type = EventType.PRE_COMPACT
+            elif "Notification" in native_type:
+                event_type = EventType.NOTIFICATION
+            elif "SubagentStop" in native_type:
+                event_type = EventType.SUBAGENT_STOP
+
+            return cls(
+                tool_name=tool_name,
+                arguments=arguments,
+                output=output,
+                event_type=event_type,
+                metadata=data,
+            )
+        except Exception:
+            return None
+
+
+@dataclass
+class PolicyResult:
+    """
+    The result of a policy evaluation.
+    """
+
+    modified_data: Any | None = None
+    should_block: bool = False
+    message: str | None = None
+    exit_code: int = 0
+
+
+class HookPolicy(ABC):
+    """
+    Abstract Base Class for unified hook policies.
+    """
+
+    @property
+    @abstractmethod
+    def event_type(self) -> EventType:
+        """The event type this policy responds to."""
+        pass
+
+    @abstractmethod
+    async def evaluate(self, event: ToolCallEvent) -> PolicyResult:
+        """
+        Evaluate the policy and return a PolicyResult.
+        """
+        pass
+
+    def as_mcp_pre_hook(self):
+        """Wraps the policy for HookManager.register_pre_tool_call."""
+
+        async def pre_hook(tool_name: str, arguments: dict[str, Any]) -> dict[str, Any] | None:
+            event = ToolCallEvent.from_mcp(tool_name, arguments)
+            result = await self.evaluate(event)
+            return result.modified_data
+
+        return pre_hook
+
+    def as_mcp_post_hook(self):
+        """Wraps the policy for HookManager.register_post_tool_call."""
+
+        async def post_hook(tool_name: str, arguments: dict[str, Any], output: str) -> str | None:
+            event = ToolCallEvent.from_mcp(tool_name, arguments, output)
+            result = await self.evaluate(event)
+            return result.modified_data
+
+        return post_hook
+
+    def run_as_native(self):
+        """Entry point for running the policy as a standalone script."""
+        event = ToolCallEvent.from_native()
+        if not event:
+            sys.exit(0)
+
+        # Allow policies to respond to multiple event types if they want,
+        # but default to strict matching.
+        if hasattr(self, "supported_event_types"):
+            if event.event_type not in self.supported_event_types:
+                sys.exit(0)
+        elif event.event_type != self.event_type:
+            sys.exit(0)
+
+        result = asyncio.run(self.evaluate(event))
+
+        if result.message:
+            # Print message to stdout for Claude to see
+            print(result.message)
+
+        if result.should_block:
+            sys.exit(result.exit_code or 2)
+
+        sys.exit(0)

mcp_bridge/hooks/git_noninteractive.py

@@ -7,7 +7,7 @@ Prevents git interactive command hangs by prepending environment variables.
 import logging
 import re
 import shlex
-from typing import Any, Dict, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -41,8 +41,8 @@ def escape_shell_arg(arg: str) -> str:
 
 
 async def git_noninteractive_hook(
-    tool_name: str, arguments: Dict[str, Any]
-) -> Optional[Dict[str, Any]]:
+    tool_name: str, arguments: dict[str, Any]
+) -> dict[str, Any] | None:
     """
     Pre-tool-call hook that prepends non-interactive env vars to git commands.
 
@@ -79,7 +79,7 @@ async def git_noninteractive_hook(
         )
         modified_command = f"{env_prefix} {command}"
 
-        logger.info(f"[GitNonInteractive] Prepending non-interactive env vars to git command")
+        logger.info("[GitNonInteractive] Prepending non-interactive env vars to git command")
 
         # Return modified arguments
         modified_args = arguments.copy()

mcp_bridge/hooks/keyword_detector.py

@@ -1,17 +1,17 @@
 """
 Keyword Detector Hook.
 
-Detects trigger keywords (ironstar, search, analyze) in user prompts
+Detects trigger keywords (ultrawork, search, analyze) in user prompts
 and injects corresponding mode activation tags.
 """
 
 import logging
 import re
-from typing import Any, Dict, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
-IRONSTAR_MODE = """<ironstar-mode>
+ULTRAWORK_MODE = """<ultrawork-mode>
 [CODE RED] Maximum precision required. Ultrathink before acting.
 
 YOU MUST LEVERAGE ALL AVAILABLE AGENTS TO THEIR FULLEST POTENTIAL.
@@ -27,7 +27,7 @@ TELL THE USER WHAT AGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
 ## EXECUTION RULES
 - **TODO**: Track EVERY step. Mark complete IMMEDIATELY after each.
 - **PARALLEL**: Fire independent agent calls simultaneously via background_task - NEVER wait sequentially.
-- **BACKGROUND FIRST**: Use background_task for exploration/research agents (10+ concurrent if needed).
+- **BACKGROUND FUWT**: Use background_task for exploration/research agents (10+ concurrent if needed).
 - **VERIFY**: Re-read request after completion. Check ALL requirements met before reporting done.
 - **DELEGATE**: Don't do everything yourself - orchestrate specialized agents for their strengths.
 
@@ -57,7 +57,7 @@ TELL THE USER WHAT AGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
 
 THE USER ASKED FOR X. DELIVER EXACTLY X. NOT A SUBSET. NOT A DEMO. NOT A STARTING POINT.
 
-</ironstar-mode>
+</ultrawork-mode>
 
 ---
 """
@@ -114,10 +114,8 @@ Use delphi agent for strategic consultation on architecture, debugging, and comp
 """
 
 KEYWORD_PATTERNS = {
-    r"\bironstar\b": IRONSTAR_MODE,
-    r"\birs\b": IRONSTAR_MODE,
-    r"\bultrawork\b": IRONSTAR_MODE,
-    r"\bulw\b": IRONSTAR_MODE,
+    r"\bultrawork\b": ULTRAWORK_MODE,
+    r"\buw\b": ULTRAWORK_MODE,
     r"\bultrathink\b": ULTRATHINK_MODE,
     r"\bsearch\b": SEARCH_MODE,
     r"\banalyze\b": ANALYZE_MODE,
@@ -125,7 +123,7 @@ KEYWORD_PATTERNS = {
 }
 
 
-async def keyword_detector_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+async def keyword_detector_hook(params: dict[str, Any]) -> dict[str, Any] | None:
     """
     Pre-model invoke hook that detects keywords and injects mode tags.
     """

mcp_bridge/hooks/manager.py

@@ -4,7 +4,8 @@ Provides interception points for tool calls and model invocations.
 """
 
 import logging
-from typing import Any, Callable, Dict, List, Optional, Awaitable
+from collections.abc import Awaitable, Callable
+from typing import Any, Optional
 
 try:
     from mcp_bridge.config.hook_config import is_hook_enabled
@@ -32,21 +33,21 @@ class HookManager:
     _instance = None
 
     def __init__(self):
-        self.pre_tool_call_hooks: List[
-            Callable[[str, Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self.pre_tool_call_hooks: list[
+            Callable[[str, dict[str, Any]], Awaitable[dict[str, Any] | None]]
         ] = []
-        self.post_tool_call_hooks: List[
-            Callable[[str, Dict[str, Any], str], Awaitable[Optional[str]]]
+        self.post_tool_call_hooks: list[
+            Callable[[str, dict[str, Any], str], Awaitable[str | None]]
         ] = []
-        self.pre_model_invoke_hooks: List[
-            Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self.pre_model_invoke_hooks: list[
+            Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]]
         ] = []
         # New hook types based on oh-my-opencode patterns
-        self.session_idle_hooks: List[
-            Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self.session_idle_hooks: list[
+            Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]]
         ] = []
-        self.pre_compact_hooks: List[
-            Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self.pre_compact_hooks: list[
+            Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]]
         ] = []
 
     @classmethod
@@ -56,38 +57,50 @@ class HookManager:
         return cls._instance
 
     def register_pre_tool_call(
-        self, hook: Callable[[str, Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self, hook: Callable[[str, dict[str, Any]], Awaitable[dict[str, Any] | None]]
     ):
         """Run before a tool is called. Can modify arguments or return early result."""
         self.pre_tool_call_hooks.append(hook)
 
     def register_post_tool_call(
-        self, hook: Callable[[str, Dict[str, Any], str], Awaitable[Optional[str]]]
+        self, hook: Callable[[str, dict[str, Any], str], Awaitable[str | None]]
     ):
         """Run after a tool call. Can modify or recover from tool output/error."""
         self.post_tool_call_hooks.append(hook)
 
     def register_pre_model_invoke(
-        self, hook: Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self, hook: Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]]
     ):
         """Run before model invocation. Can modify prompt or parameters."""
         self.pre_model_invoke_hooks.append(hook)
 
     def register_session_idle(
-        self, hook: Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self, hook: Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]]
     ):
         """Run when session becomes idle. Can inject continuation prompts."""
         self.session_idle_hooks.append(hook)
 
     def register_pre_compact(
-        self, hook: Callable[[Dict[str, Any]], Awaitable[Optional[Dict[str, Any]]]]
+        self, hook: Callable[[dict[str, Any]], Awaitable[dict[str, Any] | None]]
     ):
         """Run before context compaction. Can preserve critical context."""
         self.pre_compact_hooks.append(hook)
 
+    def register_policy(self, policy: Any):
+        """
+        Registers a unified HookPolicy.
+        Uses duck-typing to avoid circular imports.
+        """
+        from .events import EventType
+
+        if policy.event_type == EventType.PRE_TOOL_CALL:
+            self.register_pre_tool_call(policy.as_mcp_pre_hook())
+        elif policy.event_type == EventType.POST_TOOL_CALL:
+            self.register_post_tool_call(policy.as_mcp_post_hook())
+
     async def execute_pre_tool_call(
-        self, tool_name: str, arguments: Dict[str, Any]
-    ) -> Dict[str, Any]:
+        self, tool_name: str, arguments: dict[str, Any]
+    ) -> dict[str, Any]:
         """Executes all pre-tool call hooks."""
         current_args = arguments
         for hook in self.pre_tool_call_hooks:
@@ -100,7 +113,7 @@ class HookManager:
         return current_args
 
     async def execute_post_tool_call(
-        self, tool_name: str, arguments: Dict[str, Any], output: str
+        self, tool_name: str, arguments: dict[str, Any], output: str
     ) -> str:
         """Executes all post-tool call hooks."""
         current_output = output
@@ -113,7 +126,7 @@ class HookManager:
                 logger.error(f"[HookManager] Error in post_tool_call hook {hook.__name__}: {e}")
         return current_output
 
-    async def execute_pre_model_invoke(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    async def execute_pre_model_invoke(self, params: dict[str, Any]) -> dict[str, Any]:
         """Executes all pre-model invoke hooks."""
         current_params = params
         for hook in self.pre_model_invoke_hooks:
@@ -125,7 +138,7 @@ class HookManager:
                 logger.error(f"[HookManager] Error in pre_model_invoke hook {hook.__name__}: {e}")
         return current_params
 
-    async def execute_session_idle(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    async def execute_session_idle(self, params: dict[str, Any]) -> dict[str, Any]:
         """Executes all session idle hooks (Stop hook pattern)."""
         current_params = params
         for hook in self.session_idle_hooks:
@@ -137,7 +150,7 @@ class HookManager:
                 logger.error(f"[HookManager] Error in session_idle hook {hook.__name__}: {e}")
         return current_params
 
-    async def execute_pre_compact(self, params: Dict[str, Any]) -> Dict[str, Any]:
+    async def execute_pre_compact(self, params: dict[str, Any]) -> dict[str, Any]:
         """Executes all pre-compact hooks (context preservation)."""
         current_params = params
         for hook in self.pre_compact_hooks:

mcp_bridge/hooks/notification_hook.py

@@ -10,9 +10,8 @@ Example: spawned delphi:gpt-5.2-medium('Debug xyz code')
 """
 
 import json
+import os
 import sys
-from typing import Optional, Dict, Any
-
 
 # Agent display model mappings
 AGENT_DISPLAY_MODELS = {
@@ -29,7 +28,7 @@ AGENT_DISPLAY_MODELS = {
 }
 
 
-def extract_agent_info(message: str) -> Optional[Dict[str, str]]:
+def extract_agent_info(message: str) -> dict[str, str] | None:
     """
     Extract agent spawn information from notification message.
 
@@ -44,14 +43,14 @@ def extract_agent_info(message: str) -> Optional[Dict[str, str]]:
     agent_type = None
     description = ""
 
-    for agent in AGENT_DISPLAY_MODELS.keys():
+    for agent in AGENT_DISPLAY_MODELS:
         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]
+            description = message[idx + len(agent) :].strip()[:60]
             break
 
     if not agent_type:
@@ -92,8 +91,16 @@ def main():
     if not agent_info:
         return 0
 
+    # Get repo name for context
+    cwd = os.environ.get("CLAUDE_CWD", "")
+    repo_name = os.path.basename(cwd) if cwd else ""
+
     # Format and output
-    output = f"spawned {agent_info['agent_type']}:{agent_info['model']}('{agent_info['description']}')"
+    if repo_name:
+        output = f"spawned [{repo_name}] {agent_info['agent_type']}:{agent_info['model']}('{agent_info['description']}')"
+    else:
+        output = f"spawned {agent_info['agent_type']}:{agent_info['model']}('{agent_info['description']}')"
+
     print(output, file=sys.stderr)
 
     return 0

mcp_bridge/hooks/parallel_enforcement_policy.py

@@ -0,0 +1,67 @@
+import os
+import time
+
+from ..utils.session_state import get_current_session_id, get_session_state, update_session_state
+from .events import EventType, HookPolicy, PolicyResult, ToolCallEvent
+
+
+class ParallelEnforcementPolicy(HookPolicy):
+    """
+    Policy to enforce parallel delegation after TodoWrite.
+    Warns if the agent tries to use direct tools instead of Task agents
+    when multiple TODOs are pending.
+    """
+
+    @property
+    def event_type(self) -> EventType:
+        return EventType.PRE_TOOL_CALL
+
+    async def evaluate(self, event: ToolCallEvent) -> PolicyResult:
+        # We don't block agent_spawn or Task themselves
+        if event.tool_name in ["agent_spawn", "task_spawn", "Task"]:
+            return PolicyResult(modified_data=event.arguments)
+
+        session_id = event.metadata.get("session_id") or get_current_session_id()
+        state = get_session_state(session_id)
+
+        last_write = state.get("last_todo_write_at", 0)
+        pending_count = state.get("pending_todo_count", 0)
+
+        # If TodoWrite was recent (last 60 seconds) and multiple tasks are pending
+        if time.time() - last_write < 60 and pending_count >= 2:
+            # Check if this tool is allowed
+            allowed_tools = ["Read", "read_file", "ls", "list_directory"]
+            
+            # If it's a direct action tool (Bash, Edit, etc.), warn
+            if event.tool_name not in allowed_tools:
+                message = f"""
+┌──────────────────────────────────────────────────────────────────────────┐
+│                ⚠️  SEQUENTIAL EXECUTION DETECTED  ⚠️                      │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  You have {pending_count} pending tasks from your last TodoWrite.                   │
+│  You are currently attempting to use '{event.tool_name}' directly.             │
+│                                                                          │
+│  To maintain high performance and parallel workflow:                     │
+│  1. You SHOULD have spawned Task agents for all independent tasks.       │
+│  2. Direct tool use is discouraged when multiple tasks are pending.      │
+│                                                                          │
+│  If these tasks are truly independent, please use Task() instead.        │
+└──────────────────────────────────────────────────────────────────────────┘
+"""
+                # Increment warning count
+                attempts = state.get("blocked_sequential_attempts", 0) + 1
+                update_session_state({"blocked_sequential_attempts": attempts}, session_id=session_id)
+                
+                return PolicyResult(
+                    modified_data=event.arguments,
+                    message=message,
+                    # We could block here if attempts > threshold
+                )
+
+        return PolicyResult(modified_data=event.arguments)
+
+
+if __name__ == "__main__":
+    policy = ParallelEnforcementPolicy()
+    policy.run_as_native()

mcp_bridge/hooks/parallel_enforcer.py

@@ -9,7 +9,7 @@ Based on oh-my-opencode's parallel execution enforcement pattern.
 
 import logging
 import re
-from typing import Any, Dict, Optional
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -41,10 +41,10 @@ RULES:
 """
 
 # Track if enforcement was already triggered this session
-_enforcement_triggered: Dict[str, bool] = {}
+_enforcement_triggered: dict[str, bool] = {}
 
 
-async def parallel_enforcer_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+async def parallel_enforcer_hook(params: dict[str, Any]) -> dict[str, Any] | None:
     """
     Post-tool-call hook that triggers after TodoWrite.
 
@@ -106,9 +106,9 @@ def reset_enforcement(session_id: str = "default"):
 
 async def parallel_enforcer_post_tool_hook(
     tool_name: str,
-    arguments: Dict[str, Any],
+    arguments: dict[str, Any],
     output: str
-) -> Optional[str]:
+) -> str | None:
     """
     Post-tool-call hook interface for HookManager.