htmlgraph 0.26.24__py3-none-any.whl → 0.26.25__py3-none-any.whl

htmlgraph/hooks/orchestrator.py

@@ -94,6 +94,73 @@ def load_tool_history(session_id: str) -> list[dict]:
         return []
 
 
+def record_tool_event(tool_name: str, session_id: str) -> None:
+    """
+    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:
+        tool_name: Name of the tool being called
+        session_id: Session identifier for isolation
+    """
+    try:
+        import datetime
+        import uuid
+
+        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
+
+        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[str, Any], session_id: str = "unknown"
 ) -> tuple[bool, str, str]:
@@ -402,6 +469,7 @@ def enforce_orchestrator_mode(
     # Check if this is a subagent context - subagents have unrestricted tool access
     if is_subagent_context():
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
@@ -425,18 +493,14 @@ def enforce_orchestrator_mode(
         manager = OrchestratorModeManager(graph_dir)
 
         if not manager.is_enabled():
-            # Mode not active, allow everything
-            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)
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
@@ -467,6 +531,7 @@ def enforce_orchestrator_mode(
             )
 
             return {
+                "continue": False,
                 "hookSpecificOutput": {
                     "hookEventName": "PreToolUse",
                     "permissionDecision": "deny",
@@ -491,6 +556,7 @@ def enforce_orchestrator_mode(
         ):
             # Provide guidance even when allowing
             return {
+                "continue": True,
                 "hookSpecificOutput": {
                     "hookEventName": "PreToolUse",
                     "permissionDecision": "allow",
@@ -498,6 +564,7 @@ def enforce_orchestrator_mode(
                 },
             }
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
@@ -513,8 +580,8 @@ def enforce_orchestrator_mode(
     suggestion = create_task_suggestion(tool, params)
 
     if enforcement_level == "strict":
-        # STRICT mode - loud warning with violation count
-        error_message = (
+        # 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"
@@ -523,23 +590,25 @@ def enforce_orchestrator_mode(
 
         # Add circuit breaker warning if approaching threshold
         if violations >= circuit_breaker_threshold:
-            error_message += (
+            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:
-            error_message += "⚠️  Next violation will trigger circuit breaker!\n\n"
+            warning_message += "⚠️  Next violation will trigger circuit breaker!\n\n"
 
-        error_message += (
+        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:
@@ -549,6 +618,7 @@ def enforce_orchestrator_mode(
         )
 
         return {
+            "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",
                 "permissionDecision": "allow",
@@ -592,5 +662,9 @@ def main() -> None:
     # 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/session_handler.py

@@ -185,7 +185,9 @@ def handle_session_start(context: HookContext, session: Any | None) -> dict[str,
 
 {feature_list}
 
-Activity will be attributed to these features based on file patterns and keywords."""
+Activity will be attributed to these features based on file patterns and keywords.
+
+**To view all work and progress:** `htmlgraph snapshot --summary`"""
             output["hookSpecificOutput"]["sessionFeatureContext"] = context_str
             context.log("info", f"Loaded {len(active_features)} active features")
 

htmlgraph/models.py

@@ -1385,7 +1385,12 @@ class Session(BaseModel):
 
         # Build handoff HTML
         handoff_html = ""
-        if self.handoff_notes or self.recommended_next or self.blockers:
+        if (
+            self.handoff_notes
+            or self.recommended_next
+            or self.blockers
+            or self.recommended_context
+        ):
             handoff_section = """
         <section data-handoff>
             <h3>Handoff Context</h3>"""
@@ -1408,6 +1413,18 @@ class Session(BaseModel):
                 </ul>
             </div>"""
 
+            if self.recommended_context:
+                context_items = "\n                ".join(
+                    f"<li>{file_path}</li>" for file_path in self.recommended_context
+                )
+                handoff_section += f"""
+            <div data-recommended-context>
+                <strong>Recommended Context:</strong>
+                <ul>
+                    {context_items}
+                </ul>
+            </div>"""
+
             handoff_section += "\n        </section>"
             handoff_html = handoff_section
 

htmlgraph/orchestration/__init__.py

@@ -9,6 +9,7 @@ from .model_selection import (
     get_fallback_chain,
     select_model,
 )
+from .spawner_event_tracker import SpawnerEventTracker, create_tracker_from_env
 
 # Export modular spawners for advanced usage
 from .spawners import (
@@ -37,6 +38,9 @@ __all__ = [
     "CodexSpawner",
     "CopilotSpawner",
     "ClaudeSpawner",
+    # Spawner event tracking
+    "SpawnerEventTracker",
+    "create_tracker_from_env",
     # Model selection
     "ModelSelection",
     "TaskType",

htmlgraph/orchestration/plugin_manager.py

@@ -22,7 +22,7 @@ class PluginManager:
         """Get the plugin directory path.
 
         Returns:
-            Path to packages/claude-plugin/.claude-plugin
+            Path to packages/claude-plugin (the plugin root, not .claude-plugin)
         """
         # Path(__file__) = .../src/python/htmlgraph/orchestration/plugin_manager.py
         # Need to go up 5 levels to reach project root
@@ -30,7 +30,6 @@ class PluginManager:
             Path(__file__).parent.parent.parent.parent.parent
             / "packages"
             / "claude-plugin"
-            / ".claude-plugin"
         )
 
     @staticmethod

htmlgraph/orchestration/spawner_event_tracker.py

@@ -0,0 +1,383 @@
+"""Spawner event tracking helper for internal activity tracking in spawned sessions.
+
+This module provides utilities for tracking internal activities within spawner agents
+and linking them to parent delegation events for observability in HtmlGraph.
+
+Usage:
+    from htmlgraph.orchestration.spawner_event_tracker import SpawnerEventTracker
+
+    tracker = SpawnerEventTracker(
+        delegation_event_id="event-abc123",
+        parent_agent="orchestrator",
+        spawner_type="gemini"
+    )
+
+    # Track initialization phase
+    init_event = tracker.record_phase("Initializing Spawner", spawned_agent="gemini-2.0-flash")
+
+    # Track execution phase
+    exec_event = tracker.record_phase("Executing Gemini", tool_name="gemini-cli")
+    tracker.complete_phase(exec_event["event_id"], output_summary="Generated output...")
+
+    # Track completion
+    tracker.record_completion(success=True, response="Result here")
+"""
+
+import os
+import time
+import uuid
+from typing import Any
+
+
+class SpawnerEventTracker:
+    """Track internal activities in spawner agents with parent-child linking."""
+
+    def __init__(
+        self,
+        delegation_event_id: str | None = None,
+        parent_agent: str = "orchestrator",
+        spawner_type: str = "generic",
+        session_id: str | None = None,
+    ):
+        """
+        Initialize spawner event tracker.
+
+        Args:
+            delegation_event_id: Parent delegation event ID to link to
+            parent_agent: Agent that initiated the spawning
+            spawner_type: Type of spawner (gemini, codex, copilot)
+            session_id: Session ID for events
+        """
+        self.delegation_event_id = delegation_event_id
+        self.parent_agent = parent_agent
+        self.spawner_type = spawner_type
+        self.session_id = session_id or f"session-{uuid.uuid4().hex[:8]}"
+        self.db = None
+        self.phase_events: dict[str, dict[str, Any]] = {}
+        self.start_time = time.time()
+
+        # Try to initialize database for event tracking
+        try:
+            from htmlgraph.config import get_database_path
+            from htmlgraph.db.schema import HtmlGraphDB
+
+            # Get correct database path from environment or project root
+            db_path = get_database_path()
+
+            if db_path.exists():
+                self.db = HtmlGraphDB(str(db_path))
+        except Exception:
+            # Tracking is optional, continue without it
+            pass
+
+    def record_phase(
+        self,
+        phase_name: str,
+        spawned_agent: str | None = None,
+        tool_name: str | None = None,
+        input_summary: str | None = None,
+        status: str = "running",
+        parent_phase_event_id: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record the start of a phase in spawner execution.
+
+        Args:
+            phase_name: Human-readable phase name (e.g., "Initializing Spawner")
+            spawned_agent: Agent being spawned (optional)
+            tool_name: Tool being executed (optional)
+            input_summary: Summary of input (optional)
+            status: Current status (running, completed, failed)
+            parent_phase_event_id: Parent phase event ID for proper nesting (optional)
+
+        Returns:
+            Event dictionary with event_id and metadata
+        """
+        if not self.db:
+            return {}
+
+        event_id = f"event-{uuid.uuid4().hex[:8]}"
+        event_type = "tool_call"
+
+        try:
+            context = {
+                "phase_name": phase_name,
+                "spawner_type": self.spawner_type,
+                "parent_delegation_event": self.delegation_event_id,
+            }
+            if spawned_agent:
+                context["spawned_agent"] = spawned_agent
+            if tool_name:
+                context["tool"] = tool_name
+
+            # Use parent_phase_event_id if provided, otherwise use delegation_event_id
+            actual_parent_event_id = parent_phase_event_id or self.delegation_event_id
+
+            self.db.insert_event(
+                event_id=event_id,
+                agent_id=spawned_agent or self.parent_agent,
+                event_type=event_type,
+                session_id=self.session_id,
+                tool_name=tool_name
+                or f"HeadlessSpawner.{phase_name.replace(' ', '_').lower()}",
+                input_summary=input_summary or phase_name,
+                context=context,
+                parent_event_id=actual_parent_event_id,
+                subagent_type=self.spawner_type,
+            )
+
+            event = {
+                "event_id": event_id,
+                "phase_name": phase_name,
+                "spawned_agent": spawned_agent,
+                "tool_name": tool_name,
+                "status": status,
+                "start_time": time.time(),
+            }
+            self.phase_events[event_id] = event
+            return event
+
+        except Exception:
+            # Non-fatal - tracking is best-effort
+            return {}
+
+    def complete_phase(
+        self,
+        event_id: str,
+        output_summary: str | None = None,
+        status: str = "completed",
+        execution_duration: float | None = None,
+    ) -> bool:
+        """
+        Mark a phase as completed with results.
+
+        Args:
+            event_id: Event ID from record_phase
+            output_summary: Summary of output/result
+            status: Final status (completed, failed)
+            execution_duration: Execution time in seconds (auto-calculated if not provided)
+
+        Returns:
+            True if update successful, False otherwise
+        """
+        if not self.db or not event_id:
+            return False
+
+        try:
+            if execution_duration is None and event_id in self.phase_events:
+                execution_duration = (
+                    time.time() - self.phase_events[event_id]["start_time"]
+                )
+
+            if self.db.connection is None:
+                return False
+
+            cursor = self.db.connection.cursor()
+            cursor.execute(
+                """
+                UPDATE agent_events
+                SET output_summary = ?, status = ?, execution_duration_seconds = ?,
+                    updated_at = CURRENT_TIMESTAMP
+                WHERE event_id = ?
+            """,
+                (output_summary, status, execution_duration or 0.0, event_id),
+            )
+            self.db.connection.commit()
+
+            if event_id in self.phase_events:
+                self.phase_events[event_id]["status"] = status
+                self.phase_events[event_id]["output_summary"] = output_summary
+
+            return True
+        except Exception:
+            # Non-fatal
+            return False
+
+    def record_completion(
+        self,
+        success: bool,
+        response: str | None = None,
+        error: str | None = None,
+        tokens_used: int = 0,
+        cost: float = 0.0,
+    ) -> dict[str, Any]:
+        """
+        Record final completion with overall results.
+
+        Args:
+            success: Whether execution succeeded
+            response: Successful response/output
+            error: Error message if failed
+            tokens_used: Tokens consumed
+            cost: Execution cost
+
+        Returns:
+            Completion event dictionary
+        """
+        total_duration = time.time() - self.start_time
+
+        completion_event: dict[str, Any] = {
+            "success": success,
+            "duration": total_duration,
+            "tokens": tokens_used,
+            "cost": cost,
+            "phase_count": len(self.phase_events),
+        }
+
+        if success:
+            completion_event["response"] = response
+        else:
+            completion_event["error"] = error
+
+        return completion_event
+
+    def get_phase_events(self) -> dict[str, dict[str, Any]]:
+        """Get all recorded phase events."""
+        return self.phase_events
+
+    def record_tool_call(
+        self,
+        tool_name: str,
+        tool_input: dict | None,
+        phase_event_id: str,
+        spawned_agent: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Record a tool call within a spawned execution phase.
+
+        Args:
+            tool_name: Name of the tool (bash, read_file, write_file, etc.)
+            tool_input: Input parameters to the tool
+            phase_event_id: Parent phase event ID to link to
+            spawned_agent: Agent making the tool call (optional)
+
+        Returns:
+            Event dictionary with event_id and metadata
+        """
+        if not self.db:
+            return {}
+
+        event_id = f"event-{uuid.uuid4().hex[:8]}"
+
+        try:
+            context = {
+                "tool_name": tool_name,
+                "spawner_type": self.spawner_type,
+                "parent_phase_event": phase_event_id,
+            }
+            if spawned_agent:
+                context["spawned_agent"] = spawned_agent
+
+            self.db.insert_event(
+                event_id=event_id,
+                agent_id=spawned_agent or self.parent_agent,
+                event_type="tool_call",
+                session_id=self.session_id,
+                tool_name=tool_name,
+                input_summary=(
+                    str(tool_input)[:200] if tool_input else f"Call to {tool_name}"
+                ),
+                context=context,
+                parent_event_id=phase_event_id,
+                subagent_type=self.spawner_type,
+            )
+
+            tool_event = {
+                "event_id": event_id,
+                "tool_name": tool_name,
+                "tool_input": tool_input,
+                "phase_event_id": phase_event_id,
+                "spawned_agent": spawned_agent,
+                "status": "running",
+                "start_time": time.time(),
+            }
+            return tool_event
+
+        except Exception:
+            # Non-fatal - tracking is best-effort
+            return {}
+
+    def complete_tool_call(
+        self,
+        event_id: str,
+        output_summary: str | None = None,
+        success: bool = True,
+    ) -> bool:
+        """
+        Mark a tool call as complete with results.
+
+        Args:
+            event_id: Event ID from record_tool_call
+            output_summary: Summary of tool output/result
+            success: Whether the tool call succeeded
+
+        Returns:
+            True if update successful, False otherwise
+        """
+        if not self.db or not event_id:
+            return False
+
+        try:
+            if self.db.connection is None:
+                return False
+
+            cursor = self.db.connection.cursor()
+            cursor.execute(
+                """
+                UPDATE agent_events
+                SET output_summary = ?, status = ?, updated_at = CURRENT_TIMESTAMP
+                WHERE event_id = ?
+            """,
+                (
+                    output_summary,
+                    "completed" if success else "failed",
+                    event_id,
+                ),
+            )
+            self.db.connection.commit()
+            return True
+        except Exception:
+            # Non-fatal
+            return False
+
+    def get_event_hierarchy(self) -> dict[str, Any]:
+        """
+        Get the event hierarchy for this spawner execution.
+
+        Returns:
+            Dictionary with delegation event as root and phases as children
+        """
+        return {
+            "delegation_event_id": self.delegation_event_id,
+            "spawner_type": self.spawner_type,
+            "session_id": self.session_id,
+            "total_duration": time.time() - self.start_time,
+            "phase_events": self.phase_events,
+        }
+
+
+def create_tracker_from_env(
+    spawner_type: str = "generic",
+) -> SpawnerEventTracker:
+    """
+    Create a SpawnerEventTracker from environment variables.
+
+    Reads HTMLGRAPH_PARENT_EVENT, HTMLGRAPH_PARENT_AGENT, HTMLGRAPH_PARENT_SESSION
+    from environment to link to parent context.
+
+    Args:
+        spawner_type: Type of spawner (gemini, codex, copilot)
+
+    Returns:
+        Initialized SpawnerEventTracker
+    """
+    delegation_event_id = os.getenv("HTMLGRAPH_PARENT_EVENT")
+    parent_agent = os.getenv("HTMLGRAPH_PARENT_AGENT", "orchestrator")
+    session_id = os.getenv("HTMLGRAPH_PARENT_SESSION")
+
+    return SpawnerEventTracker(
+        delegation_event_id=delegation_event_id,
+        parent_agent=parent_agent,
+        spawner_type=spawner_type,
+        session_id=session_id,
+    )