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

htmlgraph/hooks/orchestrator.py

@@ -21,7 +21,7 @@ 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.
 """
 
@@ -93,7 +93,9 @@ def add_to_tool_history(tool: str) -> None:
     save_tool_history(history)
 
 
-def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, str, str]:
+def is_allowed_orchestrator_operation(
+    tool: str, params: dict[str, Any]
+) -> tuple[bool, str, str]:
     """
     Check if operation is allowed for orchestrators.
 
@@ -268,7 +270,7 @@ def is_allowed_orchestrator_operation(tool: str, params: dict) -> tuple[bool, st
         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.
 
@@ -370,7 +372,7 @@ 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]) -> dict[str, Any]:
     """
     Enforce orchestrator mode rules.
 

htmlgraph/hooks/orchestrator_reflector.py

@@ -22,7 +22,7 @@ Usage:
 """
 
 import re
-from typing import TypedDict
+from typing import Any, TypedDict
 
 
 class HookSpecificOutput(TypedDict):
@@ -93,7 +93,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 +156,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 +184,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)

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
 
@@ -343,8 +340,6 @@ def create_start_event(
     """
     tool_use_id = None
     try:
-        from pathlib import Path
-
         tool_use_id = generate_tool_use_id()
         trace_id = os.environ.get("HTMLGRAPH_TRACE_ID", tool_use_id)
         start_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
@@ -352,9 +347,10 @@ def create_start_event(
         # Sanitize input before storing
         sanitized_input = sanitize_tool_input(tool_input)
 
-        # Connect to database (use project's .htmlgraph/index.sqlite, not home directory)
-        graph_dir = Path.cwd() / ".htmlgraph"
-        db_path = str(graph_dir / "index.sqlite")
+        # Connect to database (use project's .htmlgraph/htmlgraph.db, not home directory)
+        from htmlgraph.config import get_database_path
+
+        db_path = str(get_database_path())
         db = HtmlGraphDB(db_path)
 
         # Ensure session exists (create placeholder if needed)
@@ -367,10 +363,19 @@ def create_start_event(
 
         cursor = db.connection.cursor()  # type: ignore[union-attr]
 
+        # Get UserQuery event ID for ALL tool calls (links conversation turns)
+        user_query_event_id = None
+        try:
+            from htmlgraph.hooks.event_tracker import get_parent_user_query
+
+            user_query_event_id = get_parent_user_query(db, session_id)
+        except Exception:
+            pass
+
         # Check if this is a Task() call for parent event creation
-        parent_event_id = None
+        task_parent_event_id = None
         if tool_name == "Task":
-            parent_event_id = create_task_parent_event(
+            task_parent_event_id = create_task_parent_event(
                 db, tool_input, session_id, start_time
             )
 
@@ -379,6 +384,11 @@ def create_start_event(
 
         event_id = f"evt-{str(uuid.uuid4())[:8]}"
 
+        # Determine parent: Task() uses task_parent_event, others use UserQuery
+        parent_event_id = (
+            task_parent_event_id if tool_name == "Task" else user_query_event_id
+        )
+
         cursor.execute(
             """
             INSERT INTO agent_events
@@ -395,10 +405,17 @@ def create_start_event(
                 json.dumps(sanitized_input)[:500],  # Truncate for summary
                 session_id,
                 "recorded",
-                parent_event_id,  # Link to parent if this is Task()
+                parent_event_id,  # Link to UserQuery or Task parent
             ),
         )
 
+        # Export Bash event as parent for child processes (e.g., spawner executables)
+        if tool_name == "Bash":
+            os.environ["HTMLGRAPH_PARENT_EVENT"] = event_id
+            logger.debug(
+                f"Exported HTMLGRAPH_PARENT_EVENT={event_id} for Bash tool call"
+            )
+
         # Also insert into tool_traces for correlation (if table exists)
         try:
             cursor.execute(
@@ -453,36 +470,46 @@ async def run_event_tracing(
         Event tracing response: {"hookSpecificOutput": {"tool_use_id": "...", ...}}
     """
     try:
+        from htmlgraph.hooks.context import HookContext
+
         loop = asyncio.get_event_loop()
         tool_name = tool_input.get("name", "") or tool_input.get("tool_name", "")
-        session_id = get_current_session_id()
 
-        # Skip if no session ID
-        if not session_id:
-            logger.debug("No session ID found, skipping event tracing")
-            return {}
+        # Use HookContext to properly extract session_id (same as UserPromptSubmit)
+        context = HookContext.from_input(tool_input)
 
-        # Run in thread pool since it involves I/O
-        tool_use_id = await loop.run_in_executor(
-            None,
-            create_start_event,
-            tool_name,
-            tool_input,
-            session_id,
-        )
+        try:
+            session_id = context.session_id
 
-        if tool_use_id:
-            # Store in environment for PostToolUse correlation
-            os.environ["HTMLGRAPH_TOOL_USE_ID"] = tool_use_id
+            # Skip if no session ID
+            if not session_id or session_id == "unknown":
+                logger.debug("No session ID found, skipping event tracing")
+                return {}
 
-            return {
-                "hookSpecificOutput": {
-                    "tool_use_id": tool_use_id,
-                    "additionalContext": f"Event tracing started: {tool_use_id}",
+            # Run in thread pool since it involves I/O
+            tool_use_id = await loop.run_in_executor(
+                None,
+                create_start_event,
+                tool_name,
+                tool_input,
+                session_id,
+            )
+
+            if tool_use_id:
+                # Store in environment for PostToolUse correlation
+                os.environ["HTMLGRAPH_TOOL_USE_ID"] = tool_use_id
+
+                return {
+                    "hookSpecificOutput": {
+                        "tool_use_id": tool_use_id,
+                        "additionalContext": f"Event tracing started: {tool_use_id}",
+                    }
                 }
-            }
 
-        return {}
+            return {}
+        finally:
+            # Ensure context resources are properly closed
+            context.close()
     except Exception:
         # Graceful degradation - allow on error
         return {}

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/subagent_stop.py

@@ -231,9 +231,10 @@ def handle_subagent_stop(hook_input: dict[str, Any]) -> dict[str, Any]:
 
     # Get project directory and database path
     try:
+        from htmlgraph.config import get_database_path
+
         cwd = hook_input.get("cwd", os.getcwd())
-        graph_dir = Path(cwd) / ".htmlgraph"
-        db_path = str(graph_dir / "index.sqlite")
+        db_path = str(get_database_path(cwd))
 
         if not Path(db_path).exists():
             logger.warning(f"Database not found: {db_path}")