code-muse 0.0.1__py3-none-any.whl

code_muse/hook_engine/executor.py

@@ -0,0 +1,347 @@
+"""
+Command execution engine for hooks.
+
+Handles async command execution with timeout, variable substitution,
+and comprehensive error handling.
+
+Claude Code Hook Compatibility:
+  - Input is passed via STDIN as JSON (primary method, Claude Code standard)
+  - Input is also available via CLAUDE_TOOL_INPUT env var (legacy/convenience)
+  - Exit code 0  => success, stdout shown in transcript
+  - Exit code 1  => block the operation (stderr used as reason)
+  - Exit code 2  => error feedback to Claude (stderr fed back as tool error)
+"""
+
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+from typing import Any
+
+from .matcher import _extract_file_path
+from .models import EventData, ExecutionResult, HookConfig
+from .trust import build_minimal_hook_env, cap_hook_output
+
+logger = logging.getLogger(__name__)
+
+# Max output from hooks to feed into model context
+_MAX_HOOK_STDOUT = 4096
+_MAX_HOOK_STDERR = 2048
+_MAX_HOOK_STDOUT_LINES = 256
+_MAX_HOOK_STDERR_LINES = 128
+
+
+def _build_stdin_payload(event_data: EventData) -> bytes:
+    """
+    Build the JSON payload sent to hook scripts via stdin.
+
+    Matches the Claude Code hook input format:
+    {
+        "session_id": "...",
+        "hook_event_name": "PreToolUse",
+        "tool_name": "Bash",
+        "tool_input": { ... },
+        "cwd": "/path/to/project",
+        "permission_mode": "default"
+    }
+    """
+
+    def _make_serializable(obj: Any) -> Any:
+        if isinstance(obj, dict):
+            return {k: _make_serializable(v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple)):
+            return [_make_serializable(v) for v in obj]
+        if isinstance(obj, (str, int, float, bool, type(None))):
+            return obj
+        try:
+            return str(obj)
+        except Exception:
+            return "<unserializable>"
+
+    payload = {
+        "session_id": event_data.context.get("session_id", "muse-session"),
+        "hook_event_name": event_data.event_type,
+        "tool_name": event_data.tool_name,
+        "tool_input": _make_serializable(event_data.tool_args),
+        "cwd": os.getcwd(),
+        "permission_mode": "default",
+    }
+    if "result" in event_data.context:
+        payload["tool_result"] = _make_serializable(event_data.context["result"])
+    if "duration_ms" in event_data.context:
+        payload["tool_duration_ms"] = event_data.context["duration_ms"]
+
+    return json.dumps(payload, ensure_ascii=False).encode("utf-8")
+
+
+async def execute_hook(
+    hook: HookConfig,
+    event_data: EventData,
+    env_vars: dict[str, str | None] = None,
+) -> ExecutionResult:
+    """
+    Execute a hook command with timeout and variable substitution.
+
+    Trust enforcement:
+      - Project hooks (source="project") that are not trusted are blocked
+        with a clear skipped/blocked result.
+
+    Input to the hook script:
+      - stdin: JSON object (Claude Code compatible format)
+      - env CLAUDE_TOOL_INPUT: JSON string of tool_args (legacy)
+      - env CLAUDE_PROJECT_DIR: current working directory
+
+    Exit code semantics:
+      - 0: success (stdout shown in transcript)
+      - 1: block operation (stderr becomes block reason)
+      - 2: error feedback to Claude without blocking
+    """
+    # Trust check: project hooks must be explicitly trusted
+    if hook.source == "project" and not hook.trusted:
+        return ExecutionResult(
+            blocked=True,
+            hook_command=hook.command,
+            stdout="",
+            stderr="Hook blocked: project hook not trusted. Run /trust-hooks or approve in settings.",
+            exit_code=1,
+            duration_ms=0.0,
+            error="Project hook blocked: not explicitly trusted",
+            hook_id=hook.id,
+        )
+
+    if hook.type == "prompt":
+        return ExecutionResult(
+            blocked=False,
+            hook_command=hook.command,
+            stdout=hook.command,
+            exit_code=0,
+            duration_ms=0.0,
+            hook_id=hook.id,
+        )
+
+    command = _substitute_variables(hook.command, event_data, env_vars or {})
+    stdin_payload = _build_stdin_payload(event_data)
+    start_time = time.perf_counter()
+
+    try:
+        env = _build_environment(event_data, env_vars, hook_source=hook.source)
+
+        proc = await asyncio.create_subprocess_shell(
+            command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=os.getcwd(),
+            env=env,
+        )
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(input=stdin_payload),
+                timeout=hook.timeout / 1000.0,
+            )
+        except TimeoutError:
+            try:
+                proc.kill()
+                await proc.wait()
+            except Exception:
+                pass
+
+            duration_ms = (time.perf_counter() - start_time) * 1000
+            return ExecutionResult(
+                blocked=True,
+                hook_command=command,
+                stdout="",
+                stderr=f"Command timed out after {hook.timeout}ms",
+                exit_code=-1,
+                duration_ms=duration_ms,
+                error=f"Hook execution timed out after {hook.timeout}ms",
+                hook_id=hook.id,
+            )
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+        stdout_str = stdout.decode("utf-8", errors="replace") if stdout else ""
+        stderr_str = stderr.decode("utf-8", errors="replace") if stderr else ""
+
+        # Cap output to prevent unbounded model context growth
+        stdout_str = cap_hook_output(
+            stdout_str, _MAX_HOOK_STDOUT, _MAX_HOOK_STDOUT_LINES
+        )
+        stderr_str = cap_hook_output(
+            stderr_str, _MAX_HOOK_STDERR, _MAX_HOOK_STDERR_LINES
+        )
+
+        exit_code = proc.returncode or 0
+
+        blocked = exit_code == 1
+        error = stderr_str if exit_code != 0 and stderr_str else None
+
+        return ExecutionResult(
+            blocked=blocked,
+            hook_command=command,
+            stdout=stdout_str,
+            stderr=stderr_str,
+            exit_code=exit_code,
+            duration_ms=duration_ms,
+            error=error,
+            hook_id=hook.id,
+        )
+
+    except Exception as e:
+        duration_ms = (time.perf_counter() - start_time) * 1000
+        logger.error(f"Hook execution failed: {e}", exc_info=True)
+        return ExecutionResult(
+            blocked=False,
+            hook_command=command,
+            stdout="",
+            stderr=str(e),
+            exit_code=-1,
+            duration_ms=duration_ms,
+            error=f"Hook execution error: {e}",
+            hook_id=hook.id,
+        )
+
+
+def _substitute_variables(
+    command: str,
+    event_data: EventData,
+    env_vars: dict[str, str],
+) -> str:
+    substitutions = {
+        "CLAUDE_PROJECT_DIR": os.getcwd(),
+        "tool_name": event_data.tool_name,
+        "event_type": event_data.event_type,
+        "file": _extract_file_path(event_data.tool_args) or "",
+        "CLAUDE_TOOL_INPUT": json.dumps(event_data.tool_args),
+    }
+    if event_data.context:
+        if "result" in event_data.context:
+            substitutions["result"] = str(event_data.context["result"])
+        if "duration_ms" in event_data.context:
+            substitutions["duration_ms"] = str(event_data.context["duration_ms"])
+    substitutions.update(env_vars)
+
+    result = command
+    for var, value in substitutions.items():
+        result = result.replace(f"${{{var}}}", str(value))
+        result = re.sub(
+            rf"\${re.escape(var)}(?=\W|$)", lambda m, value=value: str(value), result
+        )
+    return result
+
+
+def _build_environment(
+    event_data: EventData,
+    env_vars: dict[str, str | None] = None,
+    hook_source: str = "global",
+) -> dict[str, str]:
+    """Build environment for hook execution.
+
+    Project hooks receive a stripped-down environment with secret-like
+    variables removed. Global hooks receive the full environment.
+    """
+    env = build_minimal_hook_env() if hook_source == "project" else os.environ.copy()
+
+    env["CLAUDE_PROJECT_DIR"] = os.getcwd()
+    env["CLAUDE_TOOL_INPUT"] = json.dumps(event_data.tool_args)
+    env["CLAUDE_TOOL_NAME"] = event_data.tool_name
+    env["CLAUDE_HOOK_EVENT"] = event_data.event_type
+    env["CLAUDE_CODE_HOOK"] = "1"
+
+    file_path = _extract_file_path(event_data.tool_args)
+    if file_path:
+        env["CLAUDE_FILE_PATH"] = file_path
+
+    if env_vars:
+        env.update(env_vars)
+    return env
+
+
+async def execute_hooks_parallel(
+    hooks: list[HookConfig],
+    event_data: EventData,
+    env_vars: dict[str, str | None] = None,
+) -> list[ExecutionResult]:
+    if not hooks:
+        return []
+    tg_tasks: list[asyncio.Task[ExecutionResult]] = []
+    try:
+        async with asyncio.TaskGroup() as tg:
+            for hook in hooks:
+                tg_tasks.append(
+                    tg.create_task(execute_hook(hook, event_data, env_vars))
+                )
+    except* Exception:
+        pass  # exceptions captured per-task below
+
+    final_results = []
+    for i, task in enumerate(tg_tasks):
+        exc = task.exception()
+        if exc is not None:
+            final_results.append(
+                ExecutionResult(
+                    blocked=False,
+                    hook_command=hooks[i].command,
+                    stdout="",
+                    stderr=str(exc),
+                    exit_code=-1,
+                    duration_ms=0.0,
+                    error=f"Hook execution failed: {exc}",
+                    hook_id=hooks[i].id,
+                )
+            )
+        else:
+            final_results.append(task.result())
+    return final_results
+
+
+async def execute_hooks_sequential(
+    hooks: list[HookConfig],
+    event_data: EventData,
+    env_vars: dict[str, str | None] = None,
+    stop_on_block: bool = True,
+) -> list[ExecutionResult]:
+    results = []
+    for hook in hooks:
+        result = await execute_hook(hook, event_data, env_vars)
+        results.append(result)
+        if stop_on_block and result.blocked:
+            logger.debug(f"Hook blocked operation, stopping: {hook.command}")
+            break
+    return results
+
+
+def get_blocking_result(results: list[ExecutionResult]) -> ExecutionResult | None:
+    for result in results:
+        if result.blocked:
+            return result
+    return None
+
+
+def get_failed_results(results: list[ExecutionResult]) -> list[ExecutionResult]:
+    return [result for result in results if not result.success]
+
+
+def format_execution_summary(results: list[ExecutionResult]) -> str:
+    if not results:
+        return "No hooks executed"
+    total = len(results)
+    successful = sum(1 for r in results if r.success)
+    blocked = sum(1 for r in results if r.blocked)
+    total_duration = sum(r.duration_ms for r in results)
+    summary = [
+        f"Executed {total} hook(s)",
+        f"Successful: {successful}",
+        f"Blocked: {blocked}",
+        f"Total duration: {total_duration:.2f}ms",
+    ]
+    if blocked > 0:
+        blocking_hooks = [r for r in results if r.blocked]
+        summary.append("\nBlocking hooks:")
+        for result in blocking_hooks:
+            summary.append(f"  - {result.hook_command}")
+            if result.error:
+                summary.append(f"    Error: {result.error}")
+    return "\n".join(summary)

code_muse/hook_engine/matcher.py

@@ -0,0 +1,154 @@
+"""
+Pattern matching engine for hook filters.
+
+Provides flexible pattern matching to determine if a hook should execute
+based on tool name, arguments, and other event data.
+"""
+
+import re
+from typing import Any
+
+from .aliases import get_aliases
+
+
+def matches(matcher: str, tool_name: str, tool_args: dict[str, Any]) -> bool:
+    """
+    Evaluate if a matcher pattern matches the tool call.
+
+    Matcher Syntax:
+        - "*" - Matches all tools
+        - "ToolName" - Exact tool name match
+        - ".ext" - File extension match (e.g., ".py", ".ts")
+        - "Pattern1 && Pattern2" - AND condition (all must match)
+        - "Pattern1 || Pattern2" - OR condition (any must match)
+    """
+    if not matcher:
+        return False
+
+    if matcher.strip() == "*":
+        return True
+
+    if "||" in matcher:
+        parts = [p.strip() for p in matcher.split("||")]
+        return any(matches(part, tool_name, tool_args) for part in parts)
+
+    if "&&" in matcher:
+        parts = [p.strip() for p in matcher.split("&&")]
+        return all(matches(part, tool_name, tool_args) for part in parts)
+
+    return _match_single(matcher.strip(), tool_name, tool_args)
+
+
+def _match_single(pattern: str, tool_name: str, tool_args: dict[str, Any]) -> bool:
+    if pattern == tool_name:
+        return True
+
+    if pattern.lower() == tool_name.lower():
+        return True
+
+    # Check cross-provider aliases: a hook written for "Bash" (Claude Code) should
+    # fire when code_muse calls "agent_run_shell_command", and vice-versa.
+    tool_aliases = get_aliases(tool_name)
+    pattern_aliases = get_aliases(pattern)
+    if tool_aliases & pattern_aliases:  # non-empty intersection → same logical tool
+        return True
+
+    if pattern.startswith("."):
+        file_path = _extract_file_path(tool_args)
+        if file_path:
+            return file_path.endswith(pattern)
+        return False
+
+    if "*" in pattern:
+        parts = pattern.split("*")
+        regex_pattern = ".*".join(re.escape(part) for part in parts)
+        if re.match(f"^{regex_pattern}$", tool_name, re.IGNORECASE):
+            return True
+
+    if _is_regex_pattern(pattern):
+        try:
+            if re.search(pattern, tool_name, re.IGNORECASE):
+                return True
+            file_path = _extract_file_path(tool_args)
+            if file_path and re.search(pattern, file_path, re.IGNORECASE):
+                return True
+        except re.error:
+            pass
+
+    return False
+
+
+def _extract_file_path(tool_args: dict[str, Any]) -> str | None:
+    file_keys = [
+        "file_path",
+        "file",
+        "path",
+        "target",
+        "input_file",
+        "output_file",
+        "source",
+        "destination",
+        "src",
+        "dest",
+        "filename",
+    ]
+    for key in file_keys:
+        if key in tool_args:
+            value = tool_args[key]
+            if isinstance(value, str):
+                return value
+            if hasattr(value, "__fspath__"):
+                return str(value)
+    for value in tool_args.values():
+        if isinstance(value, str) and _looks_like_file_path(value):
+            return value
+    return None
+
+
+def _looks_like_file_path(value: str) -> bool:
+    if not value:
+        return False
+    if "." in value and not value.startswith("."):
+        parts = value.rsplit(".", 1)
+        if len(parts) == 2 and len(parts[1]) <= 10 and parts[1].isalnum():
+            return True
+    return bool("/" in value or "\\" in value)
+
+
+def _is_regex_pattern(pattern: str) -> bool:
+    regex_chars = ["^", "$", ".", "+", "?", "[", "]", "(", ")", "{", "}", "|", "\\"]
+    return any(char in pattern for char in regex_chars)
+
+
+def extract_file_extension(file_path: str) -> str | None:
+    if not file_path or "." not in file_path:
+        return None
+    if "/" in file_path:
+        file_path = file_path.rsplit("/", 1)[-1]
+    if "\\" in file_path:
+        file_path = file_path.rsplit("\\", 1)[-1]
+    if "." in file_path:
+        return "." + file_path.rsplit(".", 1)[-1]
+    return None
+
+
+def matches_tool(tool_name: str, *names: str) -> bool:
+    return tool_name.lower() in [name.lower() for name in names]
+
+
+def matches_file_extension(tool_args: dict[str, Any], *extensions: str) -> bool:
+    file_path = _extract_file_path(tool_args)
+    if not file_path:
+        return False
+    ext = extract_file_extension(file_path)
+    return ext in extensions
+
+
+def matches_file_pattern(tool_args: dict[str, Any], pattern: str) -> bool:
+    file_path = _extract_file_path(tool_args)
+    if not file_path:
+        return False
+    try:
+        return bool(re.search(pattern, file_path, re.IGNORECASE))
+    except re.error:
+        return False