htmlgraph 0.25.0__py3-none-any.whl → 0.26.1__py3-none-any.whl

htmlgraph/hooks/pretooluse.py

@@ -243,8 +243,6 @@ def create_task_parent_event(
         Parent event_id if successful, None otherwise
     """
     try:
-        from pathlib import Path
-
         if not db.connection:
             db.connect()
 
@@ -252,13 +250,12 @@ def create_task_parent_event(
         subagent_type = extract_subagent_type(tool_input)
         prompt = str(tool_input.get("prompt", ""))[:200]
 
-        # Load UserQuery event ID for parent-child linking
-        graph_dir = Path.cwd() / ".htmlgraph"
+        # Load UserQuery event ID for parent-child linking from database
         user_query_event_id = None
         try:
-            from htmlgraph.hooks.event_tracker import load_user_query_event
+            from htmlgraph.hooks.event_tracker import get_parent_user_query
 
-            user_query_event_id = load_user_query_event(graph_dir, session_id)
+            user_query_event_id = get_parent_user_query(db, session_id)
         except Exception:
             pass
 

htmlgraph/hooks/prompt_analyzer.py

@@ -15,14 +15,11 @@ The module is designed to be reusable across different hook implementations,
 with graceful degradation if dependencies are unavailable.
 """
 
-import json
 import logging
-import os
 import re
 import uuid
 from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from htmlgraph.hooks.context import HookContext
 
@@ -276,7 +273,7 @@ def get_session_violation_count(context: HookContext) -> tuple[int, int]:
         return 0, 0
 
 
-def get_active_work_item(context: HookContext) -> Optional[dict[str, Any]]:
+def get_active_work_item(context: HookContext) -> dict[str, Any] | None:
     """
     Query HtmlGraph for active feature/spike.
 
@@ -299,15 +296,18 @@ def get_active_work_item(context: HookContext) -> Optional[dict[str, Any]]:
 
         sdk = SDK()
         work_item = sdk.get_active_work_item()
-        return work_item if isinstance(work_item, dict) else None
+        if work_item is None:
+            return None
+        # Convert ActiveWorkItem TypedDict to dict
+        return dict(work_item) if hasattr(work_item, "__iter__") else work_item  # type: ignore
     except Exception as e:
         logger.debug(f"Could not get active work item: {e}")
         return None
 
 
 def generate_guidance(
-    classification: dict[str, Any], active_work: Optional[dict[str, Any]], prompt: str
-) -> Optional[str]:
+    classification: dict[str, Any], active_work: dict[str, Any] | None, prompt: str
+) -> str | None:
     """
     Generate workflow guidance based on classification and context.
 
@@ -447,7 +447,7 @@ def generate_guidance(
 
 
 def generate_cigs_guidance(
-    cigs_intent: dict, violation_count: int, waste_tokens: int
+    cigs_intent: dict[str, Any], violation_count: int, waste_tokens: int
 ) -> str:
     """
     Generate CIGS-specific guidance for detected violations.
@@ -521,13 +521,13 @@ def generate_cigs_guidance(
     return "\n".join(guidance_parts)
 
 
-def create_user_query_event(context: HookContext, prompt: str) -> Optional[str]:
+def create_user_query_event(context: HookContext, prompt: str) -> str | None:
     """
     Create UserQuery event in HtmlGraph database.
 
     Records the user prompt as a UserQuery event that serves as the parent
-    for subsequent tool calls and delegations. The event ID is saved to a
-    session-scoped file for retrieval by PreToolUse hook.
+    for subsequent tool calls and delegations. Database is the single source
+    of truth - no file-based state is used.
 
     Args:
         context: HookContext with session and database access
@@ -548,7 +548,6 @@ def create_user_query_event(context: HookContext, prompt: str) -> Optional[str]:
     """
     try:
         session_id = context.session_id
-        graph_dir = context.graph_dir
 
         if not session_id or session_id == "unknown":
             logger.debug("No valid session ID for UserQuery event")
@@ -556,9 +555,6 @@ def create_user_query_event(context: HookContext, prompt: str) -> Optional[str]:
 
         # Create UserQuery event in database
         try:
-            from htmlgraph.db.schema import HtmlGraphDB
-            from htmlgraph.hooks.event_tracker import save_user_query_event
-
             db = context.database
 
             # Ensure session exists in database before creating event
@@ -589,6 +585,8 @@ def create_user_query_event(context: HookContext, prompt: str) -> Optional[str]:
             input_summary = prompt[:200]
 
             # Insert UserQuery event into agent_events
+            # Database is the single source of truth for parent-child linking
+            # Subsequent tool calls query database via get_parent_user_query()
             success = db.insert_event(
                 event_id=user_query_event_id,
                 agent_id="user",
@@ -606,15 +604,6 @@ def create_user_query_event(context: HookContext, prompt: str) -> Optional[str]:
                 logger.warning("Failed to insert UserQuery event into database")
                 return None
 
-            # Save event ID to session-scoped file for subsequent tool calls
-            # This is used by PreToolUse hook to link Task delegations
-            try:
-                save_user_query_event(graph_dir, session_id, user_query_event_id)
-                logger.debug(f"Saved UserQuery event file: {user_query_event_id}")
-            except Exception as e:
-                # If saving to file fails, still continue (database insert succeeded)
-                logger.warning(f"Could not save UserQuery event file: {e}")
-
             logger.info(f"Created UserQuery event: {user_query_event_id}")
             return user_query_event_id
 

htmlgraph/hooks/session_handler.py

@@ -89,7 +89,7 @@ def init_or_get_session(context: HookContext) -> Any | None:
         return None
 
 
-def handle_session_start(context: HookContext, session: Any | None) -> dict:
+def handle_session_start(context: HookContext, session: Any | None) -> dict[str, Any]:
     """
     Initialize HtmlGraph tracking for the session.
 
@@ -99,6 +99,7 @@ def handle_session_start(context: HookContext, session: Any | None) -> dict:
     - Builds feature context string
     - Records session start event
     - Creates conversation-init spike if new conversation
+    - Injects concurrent session and recent work context
 
     Args:
         context: HookContext with project and graph directory information
@@ -110,6 +111,7 @@ def handle_session_start(context: HookContext, session: Any | None) -> dict:
                 "continue": True,
                 "hookSpecificOutput": {
                     "sessionFeatureContext": str with feature context,
+                    "sessionContext": optional concurrent/recent work context,
                     "versionInfo": optional version check result
                 }
             }
@@ -118,6 +120,7 @@ def handle_session_start(context: HookContext, session: Any | None) -> dict:
         "continue": True,
         "hookSpecificOutput": {
             "sessionFeatureContext": "",
+            "sessionContext": "",
             "versionInfo": None,
         },
     }
@@ -201,10 +204,61 @@ Activity will be attributed to these features based on file patterns and keyword
     except Exception as e:
         context.log("debug", f"Could not check version: {e}")
 
+    # Build concurrent session context
+    try:
+        from htmlgraph.hooks.concurrent_sessions import (
+            format_concurrent_sessions_markdown,
+            format_recent_work_markdown,
+            get_concurrent_sessions,
+            get_recent_completed_sessions,
+        )
+
+        db = context.database
+
+        # Get concurrent sessions (other active windows)
+        concurrent = get_concurrent_sessions(db, context.session_id, minutes=30)
+        concurrent_md = format_concurrent_sessions_markdown(concurrent)
+
+        # Get recent completed work
+        recent = get_recent_completed_sessions(db, hours=24, limit=5)
+        recent_md = format_recent_work_markdown(recent)
+
+        # Build session context
+        session_context = ""
+        if concurrent_md:
+            session_context += concurrent_md + "\n"
+        if recent_md:
+            session_context += recent_md + "\n"
+
+        if session_context:
+            output["hookSpecificOutput"]["sessionContext"] = session_context.strip()
+            context.log(
+                "info",
+                f"Injected context: {len(concurrent)} concurrent, {len(recent)} recent",
+            )
+
+    except ImportError:
+        context.log("debug", "Concurrent session module not available")
+    except Exception as e:
+        context.log("warning", f"Failed to get concurrent session context: {e}")
+
+    # Update session with user's current query (if available from hook input)
+    try:
+        user_query = context.hook_input.get("prompt", "")
+        if user_query and session:
+            context.session_manager.track_activity(
+                session_id=session.id,
+                tool="UserQuery",
+                summary=user_query[:100],
+                payload={"query_length": len(user_query)},
+            )
+    except Exception as e:
+        context.log("warning", f"Failed to update session activity: {e}")
+
     return output
 
 
-def handle_session_end(context: HookContext) -> dict:
+def handle_session_end(context: HookContext) -> dict[str, Any]:
     """
     Close session gracefully and record final metrics.
 
@@ -233,76 +287,75 @@ def handle_session_end(context: HookContext) -> dict:
         session = context.session_manager.get_active_session()
         if not session:
             context.log("debug", "No active session to close")
-            return output
+        else:
+            # Capture handoff context if provided
+            handoff_notes = context.hook_input.get("handoff_notes") or os.environ.get(
+                "HTMLGRAPH_HANDOFF_NOTES"
+            )
+            recommended_next = context.hook_input.get(
+                "recommended_next"
+            ) or os.environ.get("HTMLGRAPH_HANDOFF_RECOMMEND")
+            blockers_raw = context.hook_input.get("blockers") or os.environ.get(
+                "HTMLGRAPH_HANDOFF_BLOCKERS"
+            )
 
-        # Capture handoff context if provided
-        handoff_notes = context.hook_input.get("handoff_notes") or os.environ.get(
-            "HTMLGRAPH_HANDOFF_NOTES"
-        )
-        recommended_next = context.hook_input.get("recommended_next") or os.environ.get(
-            "HTMLGRAPH_HANDOFF_RECOMMEND"
-        )
-        blockers_raw = context.hook_input.get("blockers") or os.environ.get(
-            "HTMLGRAPH_HANDOFF_BLOCKERS"
-        )
+            blockers = None
+            if isinstance(blockers_raw, str):
+                blockers = [b.strip() for b in blockers_raw.split(",") if b.strip()]
+            elif isinstance(blockers_raw, list):
+                blockers = [str(b).strip() for b in blockers_raw if str(b).strip()]
 
-        blockers = None
-        if isinstance(blockers_raw, str):
-            blockers = [b.strip() for b in blockers_raw.split(",") if b.strip()]
-        elif isinstance(blockers_raw, list):
-            blockers = [str(b).strip() for b in blockers_raw if str(b).strip()]
+            if handoff_notes or recommended_next or blockers:
+                try:
+                    context.session_manager.set_session_handoff(
+                        session_id=session.id,
+                        handoff_notes=handoff_notes,
+                        recommended_next=recommended_next,
+                        blockers=blockers,
+                    )
+                    context.log("info", "Session handoff recorded")
+                except Exception as e:
+                    context.log("warning", f"Could not set handoff: {e}")
+                    output["status"] = "partial"
+
+            # Link transcript if external session ID provided
+            external_session_id = context.hook_input.get(
+                "session_id"
+            ) or os.environ.get("CLAUDE_SESSION_ID")
+            if external_session_id:
+                try:
+                    from htmlgraph.transcript import TranscriptReader
+
+                    reader = TranscriptReader()
+                    transcript = reader.read_session(external_session_id)
+                    if transcript:
+                        context.session_manager.link_transcript(
+                            session_id=session.id,
+                            transcript_id=external_session_id,
+                            transcript_path=str(transcript.path),
+                            git_branch=transcript.git_branch
+                            if hasattr(transcript, "git_branch")
+                            else None,
+                        )
+                        context.log("info", "Transcript linked to session")
+                except ImportError:
+                    context.log("debug", "Transcript reader not available")
+                except Exception as e:
+                    context.log("warning", f"Could not link transcript: {e}")
+                    output["status"] = "partial"
 
-        if handoff_notes or recommended_next or blockers:
+            # Record session end activity
             try:
-                context.session_manager.set_session_handoff(
+                context.session_manager.track_activity(
                     session_id=session.id,
-                    handoff_notes=handoff_notes,
-                    recommended_next=recommended_next,
-                    blockers=blockers,
+                    tool="SessionEnd",
+                    summary="Session ended",
                 )
-                context.log("info", "Session handoff recorded")
             except Exception as e:
-                context.log("warning", f"Could not set handoff: {e}")
+                context.log("warning", f"Could not track session end: {e}")
                 output["status"] = "partial"
 
-        # Link transcript if external session ID provided
-        external_session_id = context.hook_input.get("session_id") or os.environ.get(
-            "CLAUDE_SESSION_ID"
-        )
-        if external_session_id:
-            try:
-                from htmlgraph.transcript import TranscriptReader
-
-                reader = TranscriptReader()
-                transcript = reader.read_session(external_session_id)
-                if transcript:
-                    context.session_manager.link_transcript(
-                        session_id=session.id,
-                        transcript_id=external_session_id,
-                        transcript_path=str(transcript.path),
-                        git_branch=transcript.git_branch
-                        if hasattr(transcript, "git_branch")
-                        else None,
-                    )
-                    context.log("info", "Transcript linked to session")
-            except ImportError:
-                context.log("debug", "Transcript reader not available")
-            except Exception as e:
-                context.log("warning", f"Could not link transcript: {e}")
-                output["status"] = "partial"
-
-        # Record session end activity
-        try:
-            context.session_manager.track_activity(
-                session_id=session.id,
-                tool="SessionEnd",
-                summary="Session ended",
-            )
-        except Exception as e:
-            context.log("warning", f"Could not track session end: {e}")
-            output["status"] = "partial"
-
-        context.log("info", f"Session closed: {session.id}")
+            context.log("info", f"Session closed: {session.id}")
 
     except ImportError:
         context.log("error", "SessionManager not available")
@@ -507,7 +560,8 @@ def _get_latest_pypi_version() -> str | None:
         )
         with urllib.request.urlopen(req, timeout=5) as response:
             data = json.loads(response.read().decode())
-            return data.get("info", {}).get("version")
+            version: str | None = data.get("info", {}).get("version")
+            return version
     except Exception:
         return None
 
@@ -565,13 +619,13 @@ def _cleanup_temp_files(graph_dir: Path) -> None:
                     logger.debug(f"Could not clean up {path}: {e}")
         else:
             # Handle single file
-            path = graph_dir / pattern
+            file_path: Path = graph_dir / pattern
             try:
-                if path.exists():
-                    path.unlink()
-                    logger.debug(f"Cleaned up: {path}")
+                if file_path.exists():
+                    file_path.unlink()
+                    logger.debug(f"Cleaned up: {file_path}")
             except Exception as e:
-                logger.debug(f"Could not clean up {path}: {e}")
+                logger.debug(f"Could not clean up {file_path}: {e}")
 
 
 __all__ = [

htmlgraph/hooks/state_manager.py

@@ -25,6 +25,7 @@ import os
 import tempfile
 from datetime import datetime, timedelta
 from pathlib import Path
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -61,7 +62,7 @@ class ParentActivityTracker:
         """Ensure .htmlgraph directory exists."""
         self.graph_dir.mkdir(parents=True, exist_ok=True)
 
-    def load(self, max_age_minutes: int = 5) -> dict:
+    def load(self, max_age_minutes: int = 5) -> dict[str, Any]:
         """
         Load parent activity state.
 
@@ -334,7 +335,7 @@ class DriftQueueManager:
         """Ensure .htmlgraph directory exists."""
         self.graph_dir.mkdir(parents=True, exist_ok=True)
 
-    def load(self, max_age_hours: int = 48) -> dict:
+    def load(self, max_age_hours: int = 48) -> dict[str, Any]:
         """
         Load drift queue and filter by age.
 
@@ -393,7 +394,7 @@ class DriftQueueManager:
             logger.warning(f"Error loading drift queue: {e}")
             return {"activities": [], "last_classification": None}
 
-    def save(self, queue: dict) -> None:
+    def save(self, queue: dict[str, Any]) -> None:
         """
         Save drift queue to file.
 
@@ -425,7 +426,9 @@ class DriftQueueManager:
         except Exception as e:
             logger.error(f"Unexpected error saving drift queue: {e}")
 
-    def add_activity(self, activity: dict, timestamp: datetime | None = None) -> None:
+    def add_activity(
+        self, activity: dict[str, Any], timestamp: datetime | None = None
+    ) -> None:
         """
         Add activity to drift queue.
 

htmlgraph/hooks/validator.py

@@ -79,7 +79,7 @@ def load_tool_history() -> list[dict]:
             data = json.loads(TOOL_HISTORY_FILE.read_text())
 
             # Handle both formats: {"history": [...]} and [...] (legacy)
-            if isinstance(data, dict):
+            if isinstance(data, dict):  # type: ignore[arg-type]
                 data = data.get("history", [])
 
             # Filter to last hour only
@@ -149,7 +149,7 @@ def detect_optimal_pattern(tool: str, history: list[dict]) -> str | None:
     return OPTIMAL_PATTERNS.get(pair)
 
 
-def get_pattern_guidance(tool: str, history: list[dict]) -> dict:
+def get_pattern_guidance(tool: str, history: list[dict]) -> dict[str, Any]:
     """Get guidance based on tool patterns."""
     # Check for anti-patterns first
     anti_pattern = detect_anti_pattern(tool, history)
@@ -192,7 +192,7 @@ def get_session_health_hint(history: list[dict]) -> str | None:
     return None
 
 
-def load_validation_config() -> dict:
+def load_validation_config() -> dict[str, Any]:
     """Load validation config with defaults."""
     config_path = (
         Path(__file__).parent.parent.parent.parent.parent
@@ -218,7 +218,9 @@ def load_validation_config() -> dict:
     }
 
 
-def is_always_allowed(tool: str, params: dict, config: dict) -> bool:
+def is_always_allowed(
+    tool: str, params: dict[str, Any], config: dict[str, Any]
+) -> bool:
     """Check if tool is always allowed (read-only operations)."""
     # Always-allow tools
     if tool in config.get("always_allow", {}).get("tools", []):
@@ -234,7 +236,7 @@ def is_always_allowed(tool: str, params: dict, config: dict) -> bool:
     return False
 
 
-def is_direct_htmlgraph_write(tool: str, params: dict) -> tuple[bool, str]:
+def is_direct_htmlgraph_write(tool: str, params: dict[str, Any]) -> tuple[bool, str]:
     """Check if attempting direct write to .htmlgraph/ (always denied)."""
     if tool not in ["Write", "Edit", "Delete", "NotebookEdit"]:
         return False, ""
@@ -246,7 +248,7 @@ def is_direct_htmlgraph_write(tool: str, params: dict) -> tuple[bool, str]:
     return False, ""
 
 
-def is_sdk_command(tool: str, params: dict, config: dict) -> bool:
+def is_sdk_command(tool: str, params: dict[str, Any], config: dict[str, Any]) -> bool:
     """Check if Bash command is an SDK command."""
     if tool != "Bash":
         return False
@@ -259,7 +261,9 @@ def is_sdk_command(tool: str, params: dict, config: dict) -> bool:
     return False
 
 
-def is_code_operation(tool: str, params: dict, config: dict) -> bool:
+def is_code_operation(
+    tool: str, params: dict[str, Any], config: dict[str, Any]
+) -> bool:
     """Check if operation modifies code."""
     # Direct file operations
     if tool in config.get("code_operations", {}).get("tools", []):
@@ -288,7 +292,7 @@ def get_active_work_item() -> dict | None:
         return None
 
 
-def check_orchestrator_violation(tool: str, params: dict) -> dict | None:
+def check_orchestrator_violation(tool: str, params: dict[str, Any]) -> dict | None:
     """
     Check if operation violates orchestrator mode rules.
 
@@ -363,8 +367,8 @@ def check_orchestrator_violation(tool: str, params: dict) -> dict | None:
 
 
 def validate_tool_call(
-    tool: str, params: dict, config: dict, history: list[dict]
-) -> dict:
+    tool: str, params: dict[str, Any], config: dict[str, Any], history: list[dict]
+) -> dict[str, Any]:
     """
     Validate tool call and return GUIDANCE with active learning.
 
@@ -375,7 +379,7 @@ def validate_tool_call(
         history: Tool usage history (from load_tool_history())
 
     Returns:
-        dict: {"decision": "allow" | "block", "guidance": "...", "suggestion": "...", ...}
+        dict[str, Any]: {"decision": "allow" | "block", "guidance": "...", "suggestion": "...", ...}
               All operations are ALLOWED unless blocked for safety reasons.
 
     Example: