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

mcp_bridge/hooks/__init__.py

@@ -1,6 +1,6 @@
 """
 Hooks initialization.
-Registers all Tier 1-3 hooks into the HookManager.
+Registers all Tier 1-4 hooks into the HookManager.
 """
 
 from .manager import get_hook_manager
@@ -9,20 +9,41 @@ 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
+
 
 def initialize_hooks():
     """Register all available hooks."""
     manager = get_hook_manager()
-    
-    # Tier 1
+
+    # 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)
-    
-    # Tier 2
+    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)
-    
-    # Tier 3
+    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)
 
-# initialize_hooks()
+    # 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

mcp_bridge/hooks/agent_reminder.py

@@ -0,0 +1,61 @@
+"""
+Agent Usage Reminder Hook.
+
+When direct search tools (grep, glob, find) are used,
+suggests using background agents for more comprehensive results.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+AGENT_SUGGESTION = """
+[AGENT SUGGESTION]
+You used `{tool_name}` directly. For more comprehensive results, consider:
+
+**Background Agents (parallel, more thorough):**
+```
+background_task(agent="explore", prompt="Search for {search_context}...")
+background_task(agent="dewey", prompt="Find documentation for {search_context}...")
+```
+
+Background agents can search multiple patterns simultaneously and provide richer context.
+Use direct tools for quick, targeted lookups. Use agents for exploratory research.
+"""
+
+SEARCH_TOOLS = {"grep", "glob", "rg", "find", "Grep", "Glob", "grep_search", "glob_files"}
+
+
+async def agent_reminder_hook(
+    tool_name: str, arguments: Dict[str, Any], output: str
+) -> Optional[str]:
+    """
+    Post-tool call hook that suggests background agents after direct search tool usage.
+    """
+    if tool_name not in SEARCH_TOOLS:
+        return None
+
+    search_context = _extract_search_context(arguments)
+
+    if not search_context:
+        return None
+
+    if len(output) < 100:
+        logger.info(
+            f"[AgentReminder] Direct search '{tool_name}' returned limited results, suggesting agents"
+        )
+        suggestion = AGENT_SUGGESTION.format(tool_name=tool_name, search_context=search_context)
+        return output + "\n" + suggestion
+
+    return None
+
+
+def _extract_search_context(arguments: Dict[str, Any]) -> str:
+    """Extract search context from tool arguments."""
+    for key in ("pattern", "query", "search", "name", "path"):
+        if key in arguments:
+            value = arguments[key]
+            if isinstance(value, str) and len(value) < 100:
+                return value
+    return "related patterns"

mcp_bridge/hooks/auto_slash_command.py

@@ -0,0 +1,186 @@
+"""
+Auto Slash Command Hook.
+
+Detects and auto-processes slash commands in user input:
+- Parses `/command` patterns in user input
+- Looks up matching skill via skill_loader
+- Injects skill content into prompt
+- Registered as pre_model_invoke hook
+"""
+
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# Pattern to match slash commands at the beginning of a line or after whitespace
+SLASH_COMMAND_PATTERN = re.compile(r'(?:^|(?<=\s))\/([a-zA-Z][a-zA-Z0-9_-]*)\b', re.MULTILINE)
+
+
+def extract_slash_commands(text: str) -> List[str]:
+    """
+    Extract all slash command names from text.
+
+    Args:
+        text: Input text to scan for slash commands
+
+    Returns:
+        List of command names (without the slash)
+    """
+    matches = SLASH_COMMAND_PATTERN.findall(text)
+    # Deduplicate while preserving order
+    seen = set()
+    unique = []
+    for match in matches:
+        if match.lower() not in seen:
+            seen.add(match.lower())
+            unique.append(match)
+    return unique
+
+
+def load_skill_content(command_name: str, project_path: Optional[str] = None) -> Optional[Tuple[str, str]]:
+    """
+    Load skill content by command name.
+
+    Args:
+        command_name: The command name to look up
+        project_path: Optional project path for local skills
+
+    Returns:
+        Tuple of (skill_name, skill_content) or None if not found
+    """
+    from ..tools.skill_loader import discover_skills, parse_frontmatter
+
+    skills = discover_skills(project_path)
+
+    # Find matching skill (case-insensitive)
+    skill = next(
+        (s for s in skills if s["name"].lower() == command_name.lower()),
+        None
+    )
+
+    if not skill:
+        return None
+
+    try:
+        content = Path(skill["path"]).read_text()
+        metadata, body = parse_frontmatter(content)
+
+        # Build the skill injection block
+        skill_block = f"""
+---
+## Skill: /{skill['name']}
+**Source**: {skill['path']}
+"""
+        if metadata.get("description"):
+            skill_block += f"**Description**: {metadata['description']}\n"
+
+        if metadata.get("allowed-tools"):
+            skill_block += f"**Allowed Tools**: {metadata['allowed-tools']}\n"
+
+        skill_block += f"""
+### Instructions:
+{body}
+---
+"""
+        return skill["name"], skill_block
+
+    except Exception as e:
+        logger.error(f"[AutoSlashCommand] Error loading skill '{command_name}': {e}")
+        return None
+
+
+def get_project_path_from_prompt(prompt: str) -> Optional[str]:
+    """
+    Try to extract project path from prompt context.
+    Looks for common patterns that indicate the working directory.
+    """
+    # Look for CWD markers
+    cwd_patterns = [
+        r'CWD:\s*([^\n]+)',
+        r'Working directory:\s*([^\n]+)',
+        r'project_path["\']?\s*[:=]\s*["\']?([^"\'}\n]+)',
+    ]
+
+    for pattern in cwd_patterns:
+        match = re.search(pattern, prompt)
+        if match:
+            path = match.group(1).strip()
+            if Path(path).exists():
+                return path
+
+    return None
+
+
+SKILL_INJECTION_HEADER = """
+> **[AUTO-SKILL INJECTION]**
+> The following skill(s) have been automatically loaded based on slash commands detected in your input:
+"""
+
+SKILL_NOT_FOUND_WARNING = """
+> **[SKILL NOT FOUND]**
+> The slash command `/{command}` was detected but no matching skill was found.
+> Available skills can be listed with the `skill_list` tool.
+"""
+
+
+async def auto_slash_command_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Pre-model invoke hook that detects slash commands and injects skill content.
+
+    Scans the prompt for /command patterns and loads corresponding skill files
+    from .claude/commands/ directories.
+    """
+    prompt = params.get("prompt", "")
+
+    # Skip if already processed
+    if "[AUTO-SKILL INJECTION]" in prompt:
+        return None
+
+    # Extract slash commands
+    commands = extract_slash_commands(prompt)
+
+    if not commands:
+        return None
+
+    logger.info(f"[AutoSlashCommand] Detected slash commands: {commands}")
+
+    # Try to get project path from prompt context
+    project_path = get_project_path_from_prompt(prompt)
+
+    # Load skills for each command
+    injections = []
+    warnings = []
+    loaded_skills = []
+
+    for command in commands:
+        result = load_skill_content(command, project_path)
+        if result:
+            skill_name, skill_content = result
+            injections.append(skill_content)
+            loaded_skills.append(skill_name)
+            logger.info(f"[AutoSlashCommand] Loaded skill: {skill_name}")
+        else:
+            warnings.append(SKILL_NOT_FOUND_WARNING.format(command=command))
+            logger.warning(f"[AutoSlashCommand] Skill not found: {command}")
+
+    if not injections and not warnings:
+        return None
+
+    # Build the injection block
+    injection_block = ""
+
+    if injections:
+        injection_block = SKILL_INJECTION_HEADER
+        injection_block += f"> Skills loaded: {', '.join(loaded_skills)}\n"
+        injection_block += "\n".join(injections)
+
+    if warnings:
+        injection_block += "\n".join(warnings)
+
+    # Prepend the injection to the prompt
+    params["prompt"] = injection_block + "\n\n" + prompt
+
+    return params

mcp_bridge/hooks/comment_checker.py

@@ -0,0 +1,136 @@
+"""
+Comment Checker Hook.
+
+Warns when generated code contains excessive comments.
+Code should be self-documenting; excessive comments indicate AI slop.
+"""
+
+import logging
+import re
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+COMMENT_WARNING = """
+[WARNING - EXCESSIVE COMMENTS DETECTED]
+
+Your recent code edit contains a high ratio of comments ({ratio:.0%}).
+Code generated by stravinsky should be indistinguishable from human-written code.
+
+**Guidelines:**
+- Comments should explain WHY, not WHAT
+- Self-documenting code > commented code
+- Remove obvious comments like "// Initialize the variable"
+- Keep only: complex algorithms, security notes, performance optimizations, regex explanations
+
+**Action Required:**
+Review and remove unnecessary comments from your recent edit.
+"""
+
+COMMENT_PATTERNS = {
+    "python": [
+        r"^\s*#(?!\!)",
+        r'^\s*"""[\s\S]*?"""',
+        r"^\s*'''[\s\S]*?'''",
+    ],
+    "javascript": [
+        r"^\s*//",
+        r"/\*[\s\S]*?\*/",
+    ],
+    "typescript": [
+        r"^\s*//",
+        r"/\*[\s\S]*?\*/",
+    ],
+}
+
+CODE_EXTENSIONS = {
+    ".py": "python",
+    ".js": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".jsx": "javascript",
+}
+
+
+async def comment_checker_hook(
+    tool_name: str, arguments: Dict[str, Any], output: str
+) -> Optional[str]:
+    """
+    Post-tool call hook that checks for excessive comments in code edits.
+    """
+    if tool_name not in ("Write", "Edit", "write", "edit"):
+        return None
+
+    file_path = arguments.get("filePath", arguments.get("file_path", ""))
+    if not file_path:
+        return None
+
+    ext = None
+    for extension in CODE_EXTENSIONS:
+        if file_path.endswith(extension):
+            ext = extension
+            break
+
+    if not ext:
+        return None
+
+    lang = CODE_EXTENSIONS[ext]
+    content = arguments.get("content", arguments.get("newString", ""))
+
+    if not content or len(content) < 50:
+        return None
+
+    comment_ratio = _calculate_comment_ratio(content, lang)
+
+    if comment_ratio > 0.30:
+        logger.warning(
+            f"[CommentChecker] High comment ratio ({comment_ratio:.0%}) detected in {file_path}"
+        )
+        warning = COMMENT_WARNING.format(ratio=comment_ratio)
+        return output + "\n" + warning
+
+    return None
+
+
+def _calculate_comment_ratio(content: str, lang: str) -> float:
+    """Calculate the ratio of comment lines to total lines."""
+    lines = content.split("\n")
+    total_lines = len([l for l in lines if l.strip()])
+
+    if total_lines == 0:
+        return 0.0
+
+    comment_lines = 0
+    patterns = COMMENT_PATTERNS.get(lang, [])
+
+    in_multiline = False
+    for line in lines:
+        stripped = line.strip()
+        if not stripped:
+            continue
+
+        if lang == "python":
+            if stripped.startswith("#") and not stripped.startswith("#!"):
+                comment_lines += 1
+            elif stripped.startswith('"""') or stripped.startswith("'''"):
+                if stripped.count('"""') >= 2 or stripped.count("'''") >= 2:
+                    comment_lines += 1
+                else:
+                    in_multiline = True
+                    comment_lines += 1
+            elif in_multiline:
+                comment_lines += 1
+                if '"""' in stripped or "'''" in stripped:
+                    in_multiline = False
+        else:
+            if stripped.startswith("//"):
+                comment_lines += 1
+            elif stripped.startswith("/*"):
+                in_multiline = True
+                comment_lines += 1
+            elif in_multiline:
+                comment_lines += 1
+                if "*/" in stripped:
+                    in_multiline = False
+
+    return comment_lines / total_lines

mcp_bridge/hooks/context_monitor.py

@@ -0,0 +1,58 @@
+"""
+Context Window Monitor Hook.
+
+Monitors context window usage and provides headroom reminders.
+At 70% usage, reminds the agent there's still capacity.
+At 85%, suggests compaction before hitting hard limits.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+HEADROOM_REMINDER = """
+[CONTEXT AWARENESS]
+Current context usage: ~{usage:.0%}
+You have approximately {remaining:.0%} headroom remaining.
+Continue working - no compaction needed yet.
+"""
+
+COMPACTION_WARNING = """
+[CONTEXT WARNING - PREEMPTIVE COMPACTION RECOMMENDED]
+Current context usage: ~{usage:.0%}
+Approaching context limit. Consider:
+1. Completing current task quickly
+2. Using `background_cancel(all=true)` to clean up agents
+3. Summarizing findings before context overflow
+"""
+
+CONTEXT_THRESHOLD_REMINDER = 0.70
+CONTEXT_THRESHOLD_WARNING = 0.85
+ESTIMATED_MAX_TOKENS = 200000
+
+
+async def context_monitor_hook(params: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """
+    Pre-model invoke hook that monitors context window usage.
+    """
+    prompt = params.get("prompt", "")
+    estimated_tokens = len(prompt) / 4
+
+    usage_ratio = estimated_tokens / ESTIMATED_MAX_TOKENS
+
+    if usage_ratio >= CONTEXT_THRESHOLD_WARNING:
+        remaining = 1.0 - usage_ratio
+        logger.warning(f"[ContextMonitor] High context usage: {usage_ratio:.0%}")
+        warning = COMPACTION_WARNING.format(usage=usage_ratio, remaining=remaining)
+        params["prompt"] = prompt + "\n\n" + warning
+        return params
+
+    elif usage_ratio >= CONTEXT_THRESHOLD_REMINDER:
+        remaining = 1.0 - usage_ratio
+        logger.info(f"[ContextMonitor] Context usage: {usage_ratio:.0%}, reminding of headroom")
+        reminder = HEADROOM_REMINDER.format(usage=usage_ratio, remaining=remaining)
+        params["prompt"] = prompt + "\n\n" + reminder
+        return params
+
+    return None