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

htmlgraph/db/schema.py

@@ -163,6 +163,12 @@ class HtmlGraphDB:
             ("completed_at", "DATETIME"),
             ("last_user_query_at", "DATETIME"),
             ("last_user_query", "TEXT"),
+            # Phase 2 Feature 3: Cross-Session Continuity handoff fields
+            ("handoff_notes", "TEXT"),
+            ("recommended_next", "TEXT"),
+            ("blockers", "TEXT"),  # JSON array of blocker strings
+            ("recommended_context", "TEXT"),  # JSON array of file paths
+            ("continued_from", "TEXT"),  # Previous session ID
         ]
 
         # Refresh columns after potential rename
@@ -291,8 +297,14 @@ class HtmlGraphDB:
                 metadata JSON,
                 last_user_query_at DATETIME,
                 last_user_query TEXT,
+                handoff_notes TEXT,
+                recommended_next TEXT,
+                blockers JSON,
+                recommended_context JSON,
+                continued_from TEXT,
                 FOREIGN KEY (parent_session_id) REFERENCES sessions(session_id) ON DELETE SET NULL ON UPDATE CASCADE,
-                FOREIGN KEY (parent_event_id) REFERENCES agent_events(event_id) ON DELETE SET NULL ON UPDATE CASCADE
+                FOREIGN KEY (parent_event_id) REFERENCES agent_events(event_id) ON DELETE SET NULL ON UPDATE CASCADE,
+                FOREIGN KEY (continued_from) REFERENCES sessions(session_id) ON DELETE SET NULL ON UPDATE CASCADE
             )
         """)
 
@@ -407,6 +419,23 @@ class HtmlGraphDB:
             )
         """)
 
+        # 10. HANDOFF_TRACKING TABLE - Phase 2 Feature 3: Track handoff effectiveness
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS handoff_tracking (
+                handoff_id TEXT PRIMARY KEY,
+                from_session_id TEXT NOT NULL,
+                to_session_id TEXT,
+                items_in_context INTEGER DEFAULT 0,
+                items_accessed INTEGER DEFAULT 0,
+                time_to_resume_seconds INTEGER DEFAULT 0,
+                user_rating INTEGER CHECK(user_rating BETWEEN 1 AND 5),
+                created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                resumed_at DATETIME,
+                FOREIGN KEY (from_session_id) REFERENCES sessions(session_id) ON DELETE CASCADE,
+                FOREIGN KEY (to_session_id) REFERENCES sessions(session_id) ON DELETE SET NULL
+            )
+        """)
+
         # 9. Create indexes for performance
         self._create_indexes(cursor)
 
@@ -496,6 +525,10 @@ class HtmlGraphDB:
             # live_events indexes - optimized for real-time WebSocket streaming
             "CREATE INDEX IF NOT EXISTS idx_live_events_pending ON live_events(broadcast_at) WHERE broadcast_at IS NULL",
             "CREATE INDEX IF NOT EXISTS idx_live_events_created ON live_events(created_at DESC)",
+            # handoff_tracking indexes - optimized for handoff effectiveness queries
+            "CREATE INDEX IF NOT EXISTS idx_handoff_from_session ON handoff_tracking(from_session_id, created_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_handoff_to_session ON handoff_tracking(to_session_id, resumed_at DESC)",
+            "CREATE INDEX IF NOT EXISTS idx_handoff_rating ON handoff_tracking(user_rating, created_at DESC)",
         ]
 
         for index_sql in indexes:

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

@@ -975,10 +975,13 @@ class Session(BaseModel):
     parent_activity: str | None = None  # Parent activity ID
     nesting_depth: int = 0  # Depth of nesting (0 = top-level)
 
-    # Handoff context
+    # Handoff context (Phase 2 Feature 3: Cross-Session Continuity)
     handoff_notes: str | None = None
     recommended_next: str | None = None
     blockers: list[str] = Field(default_factory=list)
+    recommended_context: list[str] = Field(
+        default_factory=list
+    )  # File paths to keep context for
 
     # High-frequency activity log
     activity_log: list[ActivityEntry] = Field(default_factory=list)
@@ -1382,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>"""
@@ -1405,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