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

htmlgraph/db/schema.py

@@ -547,9 +547,9 @@ class HtmlGraphDB:
         try:
             cursor = self.connection.cursor()  # type: ignore[union-attr]
             # Temporarily disable foreign key constraints to allow inserting
-            # parent_event_id references that may not exist yet (will be created later)
-            if parent_event_id:
-                cursor.execute("PRAGMA foreign_keys=OFF")
+            # events even if parent_event_id or session_id don't exist yet
+            # (useful for cross-process event tracking where sessions are created asynchronously)
+            cursor.execute("PRAGMA foreign_keys=OFF")
             cursor.execute(
                 """
                 INSERT INTO agent_events
@@ -576,8 +576,7 @@ class HtmlGraphDB:
                 ),
             )
             # Re-enable foreign key constraints
-            if parent_event_id:
-                cursor.execute("PRAGMA foreign_keys=ON")
+            cursor.execute("PRAGMA foreign_keys=ON")
             self.connection.commit()  # type: ignore[union-attr]
             return True
         except sqlite3.IntegrityError as e:

htmlgraph/hooks/.htmlgraph/.session-warning-state.json

@@ -2,5 +2,5 @@
   "dismissed_at": null,
   "dismissed_by": null,
   "session_id": null,
-  "show_count": 101
+  "show_count": 121
 }

htmlgraph/hooks/context.py

@@ -101,13 +101,19 @@ class HookContext:
         # 2. hook_input["sessionId"] (camelCase variant)
         # 3. HTMLGRAPH_SESSION_ID environment variable
         # 4. CLAUDE_SESSION_ID environment variable
-        # 5. "unknown" as last resort
+        # 5. Most recent active session from database (NEW)
+        # 6. "unknown" as last resort
         #
         # NOTE: We intentionally do NOT use SessionManager.get_active_session()
         # as a fallback because the "active session" is stored in a global file
         # (.htmlgraph/session.json) that's shared across all Claude windows.
         # Using it would cause cross-window event contamination where tool calls
         # from Window B get linked to UserQuery events from Window A.
+        #
+        # However, we DO query the database by status='active' and created_at,
+        # which is different because it retrieves the most recent session that
+        # was explicitly marked as active (e.g., by SessionStart hook), without
+        # relying on a shared global agent state file.
         session_id = (
             hook_input.get("session_id")
             or hook_input.get("sessionId")
@@ -115,14 +121,40 @@ class HookContext:
             or os.environ.get("CLAUDE_SESSION_ID")
         )
 
-        # Fallback to "unknown" - better than cross-window contamination
+        # Fallback: Query database for session with most recent UserQuery event
+        # This solves the issue where PostToolUse hooks don't receive session_id
+        # in hook_input. UserPromptSubmit hooks DO receive it and create UserQuery
+        # events with the correct session_id, so we use that as the source of truth.
         if not session_id:
-            session_id = "unknown"
-            logger.warning(
-                "Could not resolve session_id from hook_input or environment. "
-                "Events will not be linked to parent UserQuery. "
-                "For multi-window support, set HTMLGRAPH_SESSION_ID env var."
-            )
+            db_path = graph_dir / "htmlgraph.db"
+            if db_path.exists():
+                try:
+                    import sqlite3
+
+                    conn = sqlite3.connect(str(db_path), timeout=1.0)
+                    cursor = conn.cursor()
+                    cursor.execute("""
+                        SELECT session_id FROM agent_events
+                        WHERE tool_name = 'UserQuery'
+                        ORDER BY timestamp DESC
+                        LIMIT 1
+                    """)
+                    row = cursor.fetchone()
+                    conn.close()
+                    if row:
+                        session_id = row[0]
+                        logger.info(f"Resolved session_id from database: {session_id}")
+                except Exception as e:
+                    logger.warning(f"Failed to query active session from database: {e}")
+
+            # Final fallback to "unknown" if database query fails
+            if not session_id:
+                session_id = "unknown"
+                logger.warning(
+                    "Could not resolve session_id from hook_input, environment, or database. "
+                    "Events will not be linked to parent UserQuery. "
+                    "For multi-window support, set HTMLGRAPH_SESSION_ID env var."
+                )
 
         # Detect agent ID (priority order)
         # 1. Explicit agent_id in hook input

htmlgraph/hooks/event_tracker.py

@@ -694,7 +694,9 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
     # Initialize SQLite database for event recording
     db = None
     try:
-        db = HtmlGraphDB(str(graph_dir / "index.sqlite"))
+        from htmlgraph.config import get_database_path
+
+        db = HtmlGraphDB(str(get_database_path()))
     except Exception as e:
         print(f"Warning: Could not initialize SQLite database: {e}", file=sys.stderr)
         # Continue without SQLite (graceful degradation)
@@ -707,18 +709,64 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
     if model_from_input:
         detected_model = model_from_input
 
-    # Get active session ID
-    active_session = manager.get_active_session()
-    if not active_session:
-        # No active HtmlGraph session yet; start one (stable internal id).
-        try:
-            active_session = manager.start_session(
-                session_id=None,
-                agent=detected_agent,
-                title=f"Session {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+    active_session = None
+
+    # Check if we're in a subagent context (environment variables set by spawner router)
+    # This MUST be checked BEFORE using get_active_session() to avoid attributing
+    # subagent events to the parent orchestrator session
+    subagent_type = os.environ.get("HTMLGRAPH_SUBAGENT_TYPE")
+    parent_session_id = os.environ.get("HTMLGRAPH_PARENT_SESSION")
+
+    if subagent_type and parent_session_id:
+        # We're in a subagent - create or get subagent session
+        # Use deterministic session ID based on parent + subagent type
+        subagent_session_id = f"{parent_session_id}-{subagent_type}"
+
+        # Check if subagent session already exists
+        existing = manager.session_converter.load(subagent_session_id)
+        if existing:
+            active_session = existing
+            print(
+                f"Debug: Using existing subagent session: {subagent_session_id}",
+                file=sys.stderr,
             )
-        except Exception:
-            return {"continue": True}
+        else:
+            # Create new subagent session with parent link
+            try:
+                active_session = manager.start_session(
+                    session_id=subagent_session_id,
+                    agent=f"{subagent_type}-spawner",
+                    is_subagent=True,
+                    parent_session_id=parent_session_id,
+                    title=f"{subagent_type.capitalize()} Subagent",
+                )
+                print(
+                    f"Debug: Created subagent session: {subagent_session_id} "
+                    f"(parent: {parent_session_id})",
+                    file=sys.stderr,
+                )
+            except Exception as e:
+                print(
+                    f"Warning: Could not create subagent session: {e}",
+                    file=sys.stderr,
+                )
+                return {"continue": True}
+
+        # Override detected agent for subagent context
+        detected_agent = f"{subagent_type}-spawner"
+    else:
+        # Normal orchestrator/parent context - use global session cache
+        active_session = manager.get_active_session()
+        if not active_session:
+            # No active HtmlGraph session yet; start one (stable internal id).
+            try:
+                active_session = manager.start_session(
+                    session_id=None,
+                    agent=detected_agent,
+                    title=f"Session {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+                )
+            except Exception:
+                return {"continue": True}
 
     active_session_id = active_session.id
 

htmlgraph/hooks/pretooluse.py

@@ -340,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")
@@ -349,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)
@@ -364,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
             )
 
@@ -376,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
@@ -392,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(
@@ -450,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/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}")

htmlgraph/operations/fastapi_server.py

@@ -79,12 +79,12 @@ def start_fastapi_server(
     if db_path is None:
         # Check for project-local database first
         project_dir = _resolve_project_dir()
-        project_db = Path(project_dir) / ".htmlgraph" / "index.sqlite"
+        project_db = Path(project_dir) / ".htmlgraph" / "htmlgraph.db"
         if project_db.exists():
             db_path = str(project_db)  # Use project-local database
         else:
             db_path = str(
-                Path.home() / ".htmlgraph" / "index.sqlite"
+                Path.home() / ".htmlgraph" / "htmlgraph.db"
             )  # Fall back to home
 
     # Ensure database exists

htmlgraph/orchestration/headless_spawner.py

@@ -3,9 +3,10 @@
 import json
 import os
 import subprocess
+import sys
 import time
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from htmlgraph.orchestration.live_events import LiveEventPublisher
@@ -463,6 +464,8 @@ class HeadlessSpawner:
         include_directories: list[str] | None = None,
         track_in_htmlgraph: bool = True,
         timeout: int = 120,
+        tracker: Any = None,
+        parent_event_id: str | None = None,
     ) -> AIResult:
         """
         Spawn Gemini in headless mode.
@@ -474,6 +477,8 @@ class HeadlessSpawner:
             include_directories: Directories to include for context. Default: None
             track_in_htmlgraph: Enable HtmlGraph activity tracking. Default: True
             timeout: Max seconds to wait
+            tracker: Optional SpawnerEventTracker for recording subprocess invocation
+            parent_event_id: Optional parent event ID for event hierarchy
 
         Returns:
             AIResult with response, error, and tracked events if tracking enabled
@@ -529,6 +534,45 @@ class HeadlessSpawner:
                 details="Running Gemini CLI",
             )
 
+            # Record subprocess invocation if tracker is available
+            subprocess_event_id = None
+            print(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
+                file=sys.stderr,
+            )
+            if tracker and parent_event_id:
+                print(
+                    "DEBUG: Recording subprocess invocation for Gemini...",
+                    file=sys.stderr,
+                )
+                try:
+                    subprocess_event = tracker.record_tool_call(
+                        tool_name="subprocess.gemini",
+                        tool_input={"cmd": cmd},
+                        phase_event_id=parent_event_id,
+                        spawned_agent="gemini-2.0-flash",
+                    )
+                    if subprocess_event:
+                        subprocess_event_id = subprocess_event.get("event_id")
+                        print(
+                            f"DEBUG: Subprocess event created for Gemini: {subprocess_event_id}",
+                            file=sys.stderr,
+                        )
+                    else:
+                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                except Exception as e:
+                    # Tracking failure should not break execution
+                    print(
+                        f"DEBUG: Exception recording Gemini subprocess: {e}",
+                        file=sys.stderr,
+                    )
+                    pass
+            else:
+                print(
+                    f"DEBUG: Skipping Gemini subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
+                    file=sys.stderr,
+                )
+
             # Execute with timeout and stderr redirection
             # Note: Cannot use capture_output with stderr parameter
             result = subprocess.run(
@@ -539,6 +583,18 @@ class HeadlessSpawner:
                 timeout=timeout,
             )
 
+            # Complete subprocess invocation tracking
+            if tracker and subprocess_event_id:
+                try:
+                    tracker.complete_tool_call(
+                        event_id=subprocess_event_id,
+                        output_summary=result.stdout[:500] if result.stdout else "",
+                        success=result.returncode == 0,
+                    )
+                except Exception:
+                    # Tracking failure should not break execution
+                    pass
+
             # Publish live event: processing response
             self._publish_live_event(
                 "spawner_phase",
@@ -755,6 +811,8 @@ class HeadlessSpawner:
         bypass_approvals: bool = False,
         track_in_htmlgraph: bool = True,
         timeout: int = 120,
+        tracker: Any = None,
+        parent_event_id: str | None = None,
     ) -> AIResult:
         """
         Spawn Codex in headless mode.
@@ -774,6 +832,8 @@ class HeadlessSpawner:
             bypass_approvals: Bypass approval checks. Default: False
             track_in_htmlgraph: Enable HtmlGraph activity tracking. Default: True
             timeout: Max seconds to wait
+            tracker: Optional SpawnerEventTracker for recording subprocess invocation
+            parent_event_id: Optional parent event ID for event hierarchy
 
         Returns:
             AIResult with response, error, and tracked events if tracking enabled
@@ -867,6 +927,45 @@ class HeadlessSpawner:
                 details="Running Codex CLI",
             )
 
+            # Record subprocess invocation if tracker is available
+            subprocess_event_id = None
+            print(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
+                file=sys.stderr,
+            )
+            if tracker and parent_event_id:
+                print(
+                    "DEBUG: Recording subprocess invocation for Codex...",
+                    file=sys.stderr,
+                )
+                try:
+                    subprocess_event = tracker.record_tool_call(
+                        tool_name="subprocess.codex",
+                        tool_input={"cmd": cmd},
+                        phase_event_id=parent_event_id,
+                        spawned_agent="gpt-4",
+                    )
+                    if subprocess_event:
+                        subprocess_event_id = subprocess_event.get("event_id")
+                        print(
+                            f"DEBUG: Subprocess event created for Codex: {subprocess_event_id}",
+                            file=sys.stderr,
+                        )
+                    else:
+                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                except Exception as e:
+                    # Tracking failure should not break execution
+                    print(
+                        f"DEBUG: Exception recording Codex subprocess: {e}",
+                        file=sys.stderr,
+                    )
+                    pass
+            else:
+                print(
+                    f"DEBUG: Skipping Codex subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
+                    file=sys.stderr,
+                )
+
             result = subprocess.run(
                 cmd,
                 stdout=subprocess.PIPE,
@@ -875,6 +974,18 @@ class HeadlessSpawner:
                 timeout=timeout,
             )
 
+            # Complete subprocess invocation tracking
+            if tracker and subprocess_event_id:
+                try:
+                    tracker.complete_tool_call(
+                        event_id=subprocess_event_id,
+                        output_summary=result.stdout[:500] if result.stdout else "",
+                        success=result.returncode == 0,
+                    )
+                except Exception:
+                    # Tracking failure should not break execution
+                    pass
+
             # Publish live event: processing
             self._publish_live_event(
                 "spawner_phase",
@@ -1035,6 +1146,8 @@ class HeadlessSpawner:
         deny_tools: list[str] | None = None,
         track_in_htmlgraph: bool = True,
         timeout: int = 120,
+        tracker: Any = None,
+        parent_event_id: str | None = None,
     ) -> AIResult:
         """
         Spawn GitHub Copilot in headless mode.
@@ -1046,6 +1159,8 @@ class HeadlessSpawner:
             deny_tools: Tools to deny (--deny-tool). Default: None
             track_in_htmlgraph: Enable HtmlGraph activity tracking. Default: True
             timeout: Max seconds to wait
+            tracker: Optional SpawnerEventTracker for recording subprocess invocation
+            parent_event_id: Optional parent event ID for event hierarchy
 
         Returns:
             AIResult with response, error, and tracked events if tracking enabled
@@ -1101,6 +1216,45 @@ class HeadlessSpawner:
                 details="Running Copilot CLI",
             )
 
+            # Record subprocess invocation if tracker is available
+            subprocess_event_id = None
+            print(
+                f"DEBUG: tracker={tracker is not None}, parent_event_id={parent_event_id}",
+                file=sys.stderr,
+            )
+            if tracker and parent_event_id:
+                print(
+                    "DEBUG: Recording subprocess invocation for Copilot...",
+                    file=sys.stderr,
+                )
+                try:
+                    subprocess_event = tracker.record_tool_call(
+                        tool_name="subprocess.copilot",
+                        tool_input={"cmd": cmd},
+                        phase_event_id=parent_event_id,
+                        spawned_agent="github-copilot",
+                    )
+                    if subprocess_event:
+                        subprocess_event_id = subprocess_event.get("event_id")
+                        print(
+                            f"DEBUG: Subprocess event created for Copilot: {subprocess_event_id}",
+                            file=sys.stderr,
+                        )
+                    else:
+                        print("DEBUG: subprocess_event was None", file=sys.stderr)
+                except Exception as e:
+                    # Tracking failure should not break execution
+                    print(
+                        f"DEBUG: Exception recording Copilot subprocess: {e}",
+                        file=sys.stderr,
+                    )
+                    pass
+            else:
+                print(
+                    f"DEBUG: Skipping Copilot subprocess tracking - tracker={tracker is not None}, parent_event_id={parent_event_id}",
+                    file=sys.stderr,
+                )
+
             result = subprocess.run(
                 cmd,
                 capture_output=True,
@@ -1108,6 +1262,18 @@ class HeadlessSpawner:
                 timeout=timeout,
             )
 
+            # Complete subprocess invocation tracking
+            if tracker and subprocess_event_id:
+                try:
+                    tracker.complete_tool_call(
+                        event_id=subprocess_event_id,
+                        output_summary=result.stdout[:500] if result.stdout else "",
+                        success=result.returncode == 0,
+                    )
+                except Exception:
+                    # Tracking failure should not break execution
+                    pass
+
             # Publish live event: processing
             self._publish_live_event(
                 "spawner_phase",