htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/hooks/orchestrator.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Orchestrator Enforcement Module
 
@@ -10,6 +14,8 @@ Architecture:
 - Classifies operations into ALLOWED vs BLOCKED categories
 - Tracks tool usage sequences to detect exploration patterns
 - Provides clear Task delegation suggestions when blocking
+- Subagents spawned via Task() have unrestricted tool access
+- Detection uses 5-level strategy: env vars, session state, database
 
 Operation Categories:
 1. ALWAYS ALLOWED - Task, AskUserQuestion, TodoWrite, SDK operations
@@ -21,85 +27,154 @@ Enforcement Levels:
 - guidance: ALLOWS but provides warnings and suggestions
 
 Public API:
-- enforce_orchestrator_mode(tool: str, params: dict) -> dict
+- enforce_orchestrator_mode(tool: str, params: dict[str, Any]) -> dict
     Main entry point for hook scripts. Returns hook response dict.
 """
 
 import json
 import re
-from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, cast
+from typing import Any
 
+from htmlgraph.hooks.subagent_detection import is_subagent_context
+from htmlgraph.orchestrator_config import load_orchestrator_config
 from htmlgraph.orchestrator_mode import OrchestratorModeManager
 from htmlgraph.orchestrator_validator import OrchestratorValidator
 
-# Tool history file (temporary storage for session)
-TOOL_HISTORY_FILE = Path("/tmp/htmlgraph-tool-history.json")
+# Maximum number of recent tool calls to consider for pattern detection
 MAX_HISTORY_SIZE = 50  # Keep last 50 tool calls
 
 
-def load_tool_history() -> list[dict]:
+def load_tool_history(session_id: str) -> list[dict]:
     """
-    Load recent tool history from temp file.
+    Load recent tool history from database (session-isolated).
+
+    Args:
+        session_id: Session identifier to filter tool history
 
     Returns:
         List of recent tool calls with tool name and timestamp
     """
-    if not TOOL_HISTORY_FILE.exists():
-        return []
-
     try:
-        data = json.loads(TOOL_HISTORY_FILE.read_text())
-        # Handle both formats: {"history": [...]} and [...] (legacy)
-        if isinstance(data, list):
-            return cast(list[dict[Any, Any]], data)
-        return cast(list[dict[Any, Any]], data.get("history", []))
+        from htmlgraph.db.schema import HtmlGraphDB
+
+        # Find database path
+        cwd = Path.cwd()
+        graph_dir = cwd / ".htmlgraph"
+        if not graph_dir.exists():
+            for parent in [cwd.parent, cwd.parent.parent, cwd.parent.parent.parent]:
+                candidate = parent / ".htmlgraph"
+                if candidate.exists():
+                    graph_dir = candidate
+                    break
+
+        db_path = graph_dir / "htmlgraph.db"
+        if not db_path.exists():
+            return []
+
+        db = HtmlGraphDB(str(db_path))
+        if db.connection is None:
+            return []
+
+        cursor = db.connection.cursor()
+        cursor.execute(
+            """
+            SELECT tool_name, timestamp
+            FROM agent_events
+            WHERE session_id = ?
+            ORDER BY timestamp DESC
+            LIMIT ?
+        """,
+            (session_id, MAX_HISTORY_SIZE),
+        )
+
+        # Return in chronological order (oldest first) for pattern detection
+        rows = cursor.fetchall()
+        db.disconnect()
+
+        return [{"tool": row[0], "timestamp": row[1]} for row in reversed(rows)]
     except Exception:
+        # Graceful degradation - return empty history on error
         return []
 
 
-def save_tool_history(history: list[dict]) -> None:
+def record_tool_event(tool_name: str, session_id: str) -> None:
     """
-    Save tool history to temp file.
+    Record a tool event to the database for history tracking.
+
+    This is called at the end of PreToolUse hook execution to track
+    tool usage patterns for sequence detection.
 
     Args:
-        history: List of tool calls to persist
+        tool_name: Name of the tool being called
+        session_id: Session identifier for isolation
     """
     try:
-        # Keep only recent history
-        recent = (
-            history[-MAX_HISTORY_SIZE:] if len(history) > MAX_HISTORY_SIZE else history
-        )
-        TOOL_HISTORY_FILE.write_text(json.dumps({"history": recent}, indent=2))
-    except Exception:
-        pass  # Fail silently on history save errors
+        import datetime
+        import uuid
 
+        from htmlgraph.db.schema import HtmlGraphDB
 
-def add_to_tool_history(tool: str) -> None:
-    """
-    Add a tool call to history.
+        # Find database path
+        cwd = Path.cwd()
+        graph_dir = cwd / ".htmlgraph"
+        if not graph_dir.exists():
+            for parent in [cwd.parent, cwd.parent.parent, cwd.parent.parent.parent]:
+                candidate = parent / ".htmlgraph"
+                if candidate.exists():
+                    graph_dir = candidate
+                    break
 
-    Args:
-        tool: Name of the tool being called
-    """
-    history = load_tool_history()
-    history.append(
-        {
-            "tool": tool,
-            "timestamp": datetime.now(timezone.utc).isoformat(),
-        }
-    )
-    save_tool_history(history)
+        if not graph_dir.exists():
+            return
+
+        db_path = graph_dir / "htmlgraph.db"
+        db = HtmlGraphDB(str(db_path))
+        if db.connection is None:
+            return
+
+        cursor = db.connection.cursor()
+        timestamp = datetime.datetime.now(datetime.timezone.utc).isoformat()
+
+        # Ensure session exists (required by FK constraint)
+        cursor.execute(
+            """
+            INSERT OR IGNORE INTO sessions (session_id, agent_assigned, created_at, status)
+            VALUES (?, ?, ?, ?)
+        """,
+            (session_id, "orchestrator-hook", timestamp, "active"),
+        )
+
+        # Record the tool event using the actual schema
+        # Schema has: event_id, agent_id, event_type, timestamp, tool_name, session_id, etc.
+        event_id = str(uuid.uuid4())
+        agent_id = "orchestrator-hook"  # Identifier for the hook
+
+        cursor.execute(
+            """
+            INSERT INTO agent_events (event_id, agent_id, event_type, timestamp, tool_name, session_id)
+            VALUES (?, ?, ?, ?, ?, ?)
+        """,
+            (event_id, agent_id, "tool_call", timestamp, tool_name, session_id),
+        )
+
+        db.connection.commit()
+        db.disconnect()
+    except Exception:
+        # Graceful degradation - don't fail hook on recording error
+        pass
 
 
-def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, str, str]:
+def is_allowed_orchestrator_operation(
+    tool: str, params: dict[str, Any], session_id: str = "unknown"
+) -> tuple[bool, str, str]:
     """
     Check if operation is allowed for orchestrators.
 
     Args:
         tool: Tool name (e.g., "Read", "Edit", "Bash")
         params: Tool parameters dict
+        session_id: Session identifier for loading tool history
 
     Returns:
         Tuple of (is_allowed, reason_if_not, category)
@@ -107,6 +182,23 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
         - reason_if_not: Explanation if blocked (empty if allowed)
         - category: Operation category for logging
     """
+    # Get enforcement level from manager
+    try:
+        cwd = Path.cwd()
+        graph_dir = cwd / ".htmlgraph"
+        if not graph_dir.exists():
+            for parent in [cwd.parent, cwd.parent.parent, cwd.parent.parent.parent]:
+                candidate = parent / ".htmlgraph"
+                if candidate.exists():
+                    graph_dir = candidate
+                    break
+        manager = OrchestratorModeManager(graph_dir)
+        enforcement_level = (
+            manager.get_enforcement_level() if manager.is_enabled() else "guidance"
+        )
+    except Exception:
+        enforcement_level = "guidance"
+
     # Use OrchestratorValidator for comprehensive validation
     validator = OrchestratorValidator()
     result, reason = validator.validate_tool_use(tool, params)
@@ -121,6 +213,10 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
     if tool in ["Task", "AskUserQuestion", "TodoWrite"]:
         return True, "", "orchestrator-core"
 
+    # FIX #2: Block Skills in strict mode (must be invoked via Task delegation)
+    if tool == "Skill" and enforcement_level == "strict":
+        return False, "Skills must be invoked via Task delegation", "skill-blocked"
+
     # Category 2: SDK Operations - Always allowed
     if tool == "Bash":
         command = params.get("command", "")
@@ -129,22 +225,66 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
         if command.startswith("uv run htmlgraph ") or command.startswith("htmlgraph "):
             return True, "", "sdk-command"
 
-        # Allow git read-only commands
-        if (
-            command.startswith("git status")
-            or command.startswith("git diff")
-            or command.startswith("git log")
-        ):
-            return True, "", "git-readonly"
+        # Allow git read-only commands using shared classification
+        if command.strip().startswith("git"):
+            from htmlgraph.hooks.git_commands import should_allow_git_command
+
+            if should_allow_git_command(command):
+                return True, "", "git-readonly"
 
         # Allow SDK inline usage (Python inline with htmlgraph import)
         if "from htmlgraph import" in command or "import htmlgraph" in command:
             return True, "", "sdk-inline"
 
+        # FIX #3: Check if bash command is in allowed whitelist (strict mode only)
+        # If we've gotten here, it's not a whitelisted command above
+        # Block non-whitelisted bash commands in strict mode
+        if enforcement_level == "strict":
+            # Check if it's a blocked test/build pattern (handled below)
+            blocked_patterns = [
+                r"^npm (run|test|build)",
+                r"^pytest",
+                r"^uv run pytest",
+                r"^python -m pytest",
+                r"^cargo (build|test)",
+                r"^mvn (compile|test|package)",
+                r"^make (test|build)",
+            ]
+            is_blocked_pattern = any(
+                re.match(pattern, command) for pattern in blocked_patterns
+            )
+
+            if not is_blocked_pattern:
+                # Not a specifically blocked pattern, but also not whitelisted
+                # In strict mode, we should delegate
+                return (
+                    False,
+                    f"Bash command not in allowed list. Delegate to subagent.\n\n"
+                    f"Command: {command[:100]}",
+                    "bash-blocked",
+                )
+
     # Category 3: Quick Lookups - Single operations only
     if tool in ["Read", "Grep", "Glob"]:
         # Check tool history to see if this is a single lookup or part of a sequence
-        history = load_tool_history()
+        history = load_tool_history(session_id)
+
+        # FIX #4: Check for mixed exploration pattern (configurable threshold)
+        config = load_orchestrator_config()
+        exploration_threshold = config.thresholds.exploration_calls
+
+        # Check last N calls (where N = threshold + 2)
+        lookback = min(exploration_threshold + 2, len(history))
+        exploration_count = sum(
+            1 for h in history[-lookback:] if h["tool"] in ["Read", "Grep", "Glob"]
+        )
+        if exploration_count >= exploration_threshold and enforcement_level == "strict":
+            return (
+                False,
+                f"Multiple exploration calls detected ({exploration_count}/{exploration_threshold}). Delegate to Explorer agent.\n\n"
+                "Use Task tool with explorer subagent.",
+                "exploration-blocked",
+            )
 
         # Look at last 3 tool calls
         recent_same_tool = sum(1 for h in history[-3:] if h["tool"] == tool)
@@ -181,7 +321,7 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
         command = params.get("command", "")
 
         # Block compilation, testing, building (should be in subagent)
-        blocked_patterns = [
+        test_build_patterns: list[tuple[str, str]] = [
             (r"^npm (run|test|build)", "npm test/build"),
             (r"^pytest", "pytest"),
             (r"^uv run pytest", "pytest"),
@@ -191,7 +331,7 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
             (r"^make (test|build)", "make test/build"),
         ]
 
-        for pattern, name in blocked_patterns:
+        for pattern, name in test_build_patterns:
             if re.match(pattern, command):
                 return (
                     False,
@@ -200,11 +340,14 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
                     "test-build-blocked",
                 )
 
-    # Default: Allow with guidance
-    return True, "Allowed but consider if delegation would be better", "allowed-default"
+    # FIX #1: Remove "allowed-default" escape hatch in strict mode
+    if enforcement_level == "strict":
+        return False, "Not in allowed whitelist", "strict-blocked"
+    else:
+        return True, "Allowed in guidance mode", "guidance-allowed"
 
 
-def create_task_suggestion(tool: str, params: dict) -> str:
+def create_task_suggestion(tool: str, params: dict[str, Any]) -> str:
     """
     Create Task tool suggestion based on blocked operation.
 
@@ -306,21 +449,37 @@ def create_task_suggestion(tool: str, params: dict) -> str:
     )
 
 
-def enforce_orchestrator_mode(tool: str, params: dict) -> dict:
+def enforce_orchestrator_mode(
+    tool: str, params: dict[str, Any], session_id: str = "unknown"
+) -> dict[str, Any]:
     """
     Enforce orchestrator mode rules.
 
     This is the main public API for hook scripts. It checks if orchestrator mode
     is enabled, classifies the operation, and returns a hook response dict.
 
+    Subagents spawned via Task() have unrestricted tool access.
+    Detection uses 5-level strategy: env vars, session state, database.
+
     Args:
         tool: Tool being called
         params: Tool parameters
+        session_id: Session identifier for loading tool history
 
     Returns:
         Hook response dict with decision (allow/block) and guidance
         Format: {"continue": bool, "hookSpecificOutput": {...}}
     """
+    # Check if this is a subagent context - subagents have unrestricted tool access
+    if is_subagent_context():
+        return {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+            },
+        }
+
     # Get manager and check if mode is enabled
     try:
         # Look for .htmlgraph directory starting from cwd
@@ -338,31 +497,59 @@ def enforce_orchestrator_mode(tool: str, params: dict) -> dict:
         manager = OrchestratorModeManager(graph_dir)
 
         if not manager.is_enabled():
-            # Mode not active, allow everything
-            add_to_tool_history(tool)
-            return {
-                "hookSpecificOutput": {
-                    "hookEventName": "PreToolUse",
-                    "permissionDecision": "allow",
-                },
-            }
+            # Mode not active, allow everything with no additional output
+            return {"continue": True}
 
         enforcement_level = manager.get_enforcement_level()
     except Exception:
         # If we can't check mode, fail open (allow)
-        add_to_tool_history(tool)
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
             },
         }
 
-    # Check if operation is allowed
-    is_allowed, reason, category = is_allowed_orchestrator_operation(tool, params)
+    # Check if circuit breaker is triggered in strict mode (configurable threshold)
+    config = load_orchestrator_config()
+    circuit_breaker_threshold = config.thresholds.circuit_breaker_violations
+
+    if enforcement_level == "strict" and manager.is_circuit_breaker_triggered():
+        # Circuit breaker triggered - block all non-core operations
+        if tool not in ["Task", "AskUserQuestion", "TodoWrite"]:
+            violation_count = manager.get_violation_count()
+            circuit_breaker_message = (
+                "🚨 ORCHESTRATOR CIRCUIT BREAKER TRIGGERED\n\n"
+                f"You have violated delegation rules {violation_count} times this session "
+                f"(threshold: {circuit_breaker_threshold}).\n\n"
+                "Violations detected:\n"
+                "- Direct execution instead of delegation\n"
+                "- Context waste on tactical operations\n\n"
+                "Options:\n"
+                "1. Disable orchestrator mode: uv run htmlgraph orchestrator disable\n"
+                "2. Change to guidance mode: uv run htmlgraph orchestrator set-level guidance\n"
+                "3. Reset counter (acknowledge violations): uv run htmlgraph orchestrator reset-violations\n"
+                "4. Adjust thresholds: uv run htmlgraph orchestrator config set thresholds.circuit_breaker_violations <N>\n\n"
+                "To proceed, choose an option above."
+            )
+
+            return {
+                "continue": False,
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": circuit_breaker_message,
+                },
+            }
+
+    # Check if operation is allowed (pass session_id for history lookup)
+    is_allowed, reason, category = is_allowed_orchestrator_operation(
+        tool, params, session_id
+    )
 
-    # Add to history (for sequence detection)
-    add_to_tool_history(tool)
+    # Note: Tool recording is now handled by track-event.py PostToolUse hook
+    # No need to call add_to_tool_history() here
 
     # Operation is allowed
     if is_allowed:
@@ -373,6 +560,7 @@ def enforce_orchestrator_mode(tool: str, params: dict) -> dict:
         ):
             # Provide guidance even when allowing
             return {
+                "continue": True,
                 "hookSpecificOutput": {
                     "hookEventName": "PreToolUse",
                     "permissionDecision": "allow",
@@ -380,32 +568,51 @@ def enforce_orchestrator_mode(tool: str, params: dict) -> dict:
                 },
             }
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
             },
         }
 
-    # Operation not allowed - provide strong warnings
-    # NOTE: {"continue": False} doesn't work in Claude Code, so we use advisory warnings only
+    # Operation not allowed - track violation and provide warnings
+    if enforcement_level == "strict":
+        # Increment violation counter
+        mode = manager.increment_violation()
+        violations = mode.violations
+
     suggestion = create_task_suggestion(tool, params)
 
     if enforcement_level == "strict":
-        # STRICT mode - loud warning but allow (blocking doesn't work)
-        error_message = (
-            f"🚫 ORCHESTRATOR MODE VIOLATION: {reason}\n\n"
+        # STRICT mode - advisory warning with violation count (does not block)
+        warning_message = (
+            f"🚫 ORCHESTRATOR MODE VIOLATION ({violations}/{circuit_breaker_threshold}): {reason}\n\n"
             f"⚠️  WARNING: Direct operations waste context and break delegation pattern!\n\n"
             f"Suggested delegation:\n"
             f"{suggestion}\n\n"
-            f"See ORCHESTRATOR_DIRECTIVES in session context for HtmlGraph delegation pattern.\n"
-            f"To disable orchestrator mode: uv run htmlgraph orchestrator disable"
         )
 
+        # Add circuit breaker warning if approaching threshold
+        if violations >= circuit_breaker_threshold:
+            warning_message += (
+                "🚨 CIRCUIT BREAKER TRIGGERED - Further violations will be blocked!\n\n"
+                "Reset with: uv run htmlgraph orchestrator reset-violations\n"
+            )
+        elif violations == circuit_breaker_threshold - 1:
+            warning_message += "⚠️  Next violation will trigger circuit breaker!\n\n"
+
+        warning_message += (
+            "See ORCHESTRATOR_DIRECTIVES in session context for HtmlGraph delegation pattern.\n"
+            "To disable orchestrator mode: uv run htmlgraph orchestrator disable"
+        )
+
+        # Advisory-only: allow operation but provide warning
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
-                "permissionDecision": "deny",
-                "permissionDecisionReason": error_message,
+                "permissionDecision": "allow",
+                "additionalContext": warning_message,
             },
         }
     else:
@@ -415,9 +622,53 @@ def enforce_orchestrator_mode(tool: str, params: dict) -> dict:
         )
 
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
                 "additionalContext": warning_message,
             },
         }
+
+
+def main() -> None:
+    """Hook entry point for script wrapper."""
+    import os
+    import sys
+
+    # Check if tracking is disabled
+    if os.environ.get("HTMLGRAPH_DISABLE_TRACKING") == "1":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check for orchestrator mode environment override
+    if os.environ.get("HTMLGRAPH_ORCHESTRATOR_DISABLED") == "1":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Get tool name and parameters (Claude Code uses "name" and "input")
+    tool_name = hook_input.get("name", "") or hook_input.get("tool_name", "")
+    tool_input = hook_input.get("input", {}) or hook_input.get("tool_input", {})
+
+    # Get session_id from hook_input (NEW: required for session-isolated history)
+    session_id = hook_input.get("session_id", "unknown")
+
+    if not tool_name:
+        # No tool name, allow
+        print(json.dumps({"continue": True}))
+        return
+
+    # Enforce orchestrator mode with session_id for history lookup
+    response = enforce_orchestrator_mode(tool_name, tool_input, session_id)
+
+    # Record tool event to database for history tracking
+    # This allows subsequent calls to detect patterns (e.g., multiple Reads)
+    record_tool_event(tool_name, session_id)
+
+    # Output JSON response
+    print(json.dumps(response))

htmlgraph/hooks/orchestrator_reflector.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Orchestrator Reflection Module
 
@@ -22,7 +26,7 @@ Usage:
 """
 
 import re
-from typing import TypedDict
+from typing import Any, TypedDict
 
 
 class HookSpecificOutput(TypedDict):
@@ -93,7 +97,7 @@ def is_python_execution(command: str) -> bool:
     return False
 
 
-def should_reflect(hook_input: dict) -> tuple[bool, str]:
+def should_reflect(hook_input: dict[str, Any]) -> tuple[bool, str]:
     """
     Check if we should show reflection prompt.
 
@@ -156,7 +160,7 @@ Ask yourself:
 Continue, but consider delegation for similar future tasks."""
 
 
-def orchestrator_reflect(tool_input: dict) -> dict:
+def orchestrator_reflect(tool_input: dict[str, Any]) -> dict[str, Any]:
     """
     Main API function for orchestrator reflection.
 
@@ -184,7 +188,7 @@ def orchestrator_reflect(tool_input: dict) -> dict:
     should_show, command_preview = should_reflect(tool_input)
 
     # Build response
-    response: dict = {"continue": True}
+    response: dict[str, Any] = {"continue": True}
 
     if should_show:
         reflection = build_reflection_message(command_preview)
@@ -194,3 +198,26 @@ def orchestrator_reflect(tool_input: dict) -> dict:
         }
 
     return response
+
+
+def main() -> None:
+    """Hook entry point for script wrapper."""
+    import json
+    import os
+    import sys
+
+    # Check if tracking is disabled
+    if os.environ.get("HTMLGRAPH_DISABLE_TRACKING") == "1":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        hook_input = {}
+
+    # Run reflection logic
+    response = orchestrator_reflect(hook_input)
+
+    # Output JSON response
+    print(json.dumps(response))