htmlgraph 0.26.4__py3-none-any.whl → 0.26.6__py3-none-any.whl

htmlgraph/db/schema.py

@@ -96,6 +96,7 @@ class HtmlGraphDB:
 
         # Add missing columns with defaults
         migrations = [
+            ("feature_id", "TEXT"),
             ("subagent_type", "TEXT"),
             ("child_spike_count", "INTEGER DEFAULT 0"),
             ("cost_tokens", "INTEGER DEFAULT 0"),
@@ -216,6 +217,7 @@ class HtmlGraphDB:
                 output_summary TEXT,
                 context JSON,
                 session_id TEXT NOT NULL,
+                feature_id TEXT,
                 parent_agent_id TEXT,
                 parent_event_id TEXT,
                 subagent_type TEXT,
@@ -227,7 +229,8 @@ class HtmlGraphDB:
                 created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                 updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
                 FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE 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 (feature_id) REFERENCES features(id) ON DELETE SET NULL ON UPDATE CASCADE
             )
         """)
 
@@ -513,6 +516,7 @@ class HtmlGraphDB:
         execution_duration_seconds: float = 0.0,
         subagent_type: str | None = None,
         model: str | None = None,
+        feature_id: str | None = None,
     ) -> bool:
         """
         Insert an agent event into the database.
@@ -553,16 +557,17 @@ class HtmlGraphDB:
             cursor.execute(
                 """
                 INSERT INTO agent_events
-                (event_id, agent_id, event_type, session_id, tool_name,
+                (event_id, agent_id, event_type, session_id, feature_id, tool_name,
                  input_summary, output_summary, context, parent_agent_id,
                  parent_event_id, cost_tokens, execution_duration_seconds, subagent_type, model)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
                 (
                     event_id,
                     agent_id,
                     event_type,
                     session_id,
+                    feature_id,
                     tool_name,
                     input_summary,
                     output_summary,

htmlgraph/docs/ORCHESTRATION_PATTERNS.md

@@ -32,8 +32,8 @@ result = spawner.spawn_claude(
 )
 
 result = spawner.spawn_gemini(
-    prompt="Analyze codebase for performance issues",
-    model="gemini-2.0-flash"
+    prompt="Analyze codebase for performance issues"
+    # model=None (default) - uses latest Gemini models including Gemini 3 preview
 )
 
 result = spawner.spawn_codex(
@@ -88,7 +88,7 @@ else:
 ```python
 result = spawner.spawn_gemini(
     prompt="Analyze this code for security issues",
-    model="gemini-2.0-flash",     # Latest Gemini model
+    # model=None (default) - RECOMMENDED: uses latest Gemini models
     temperature=0.7,               # Creativity (0-1)
     output_json=False
 )
@@ -99,10 +99,17 @@ else:
     print(f"Error: {result.error}")
 ```
 
-**Gemini Models:**
-- `gemini-2.0-flash` - Latest, fastest
-- `gemini-1.5-pro` - More capable
-- `gemini-1.5-flash` - Faster, cheaper
+**Gemini Model Selection:**
+- `None` (default) - **RECOMMENDED**: CLI chooses best available model (gemini-2.5-flash-lite, gemini-3-flash-preview)
+- Explicit model specification is DISCOURAGED - older models may fail with newer CLI versions
+
+**Available models (if you must specify):**
+- `gemini-2.5-flash-lite` - Fast, efficient
+- `gemini-3-flash-preview` - Gemini 3 with enhanced capabilities
+- `gemini-2.5-pro` - More capable, slower
+
+**DEPRECATED models (may cause errors):**
+- `gemini-2.0-flash`, `gemini-1.5-pro`, `gemini-1.5-flash` - Use `None` instead
 
 ---
 
@@ -174,8 +181,8 @@ if model == "gpt-4-turbo":
     result = spawner.spawn_codex(prompt="...", model=model)
 elif model == "claude-opus":
     result = spawner.spawn_claude(prompt="...", model=model)
-elif model == "gemini-2.0-flash":
-    result = spawner.spawn_gemini(prompt="...", model=model)
+elif model.startswith("gemini"):
+    result = spawner.spawn_gemini(prompt="...")  # model=None recommended
 ```
 
 **Task Types:**
@@ -427,8 +434,8 @@ Decompose complex tasks into subtasks:
 ```python
 # Step 1: Analysis (cheap/fast)
 analysis_result = spawner.spawn_gemini(
-    prompt="Analyze the codebase structure",
-    model="gemini-2.0-flash"
+    prompt="Analyze the codebase structure"
+    # model=None - uses latest Gemini models (Gemini 3 preview)
 )
 
 # Step 2: Design (more capable)
@@ -559,8 +566,8 @@ def get_consensus(prompt, num_agents=3):
         prompt=prompt, model="claude-opus"
     )))
 
-    results.append(("gemini-2.0-flash", spawner.spawn_gemini(
-        prompt=prompt, model="gemini-2.0-flash"
+    results.append(("gemini", spawner.spawn_gemini(
+        prompt=prompt  # model=None uses latest Gemini models
     )))
 
     results.append(("gpt-4-turbo", spawner.spawn_codex(

htmlgraph/docs/README.md

@@ -198,10 +198,9 @@ result = spawner.spawn_claude(
     approval="auto"
 )
 
-# Spawn Gemini
+# Spawn Gemini (model=None uses latest models including Gemini 3 preview)
 result = spawner.spawn_gemini(
-    prompt="Analyze performance",
-    model="gemini-2.0-flash"
+    prompt="Analyze performance"
 )
 
 # Spawn Codex

htmlgraph/hooks/event_tracker.py

@@ -446,6 +446,77 @@ def detect_agent_from_environment() -> tuple[str, str | None]:
     return agent_id, model_name
 
 
+def detect_subagent_context_from_database(
+    db: HtmlGraphDB, current_session_id: str
+) -> tuple[str | None, str | None, str | None]:
+    """
+    Detect if we're in a subagent context by checking for active task_delegation events.
+
+    This is the DATABASE-BASED approach to subagent detection, which is necessary because
+    environment variables set by PreToolUse hooks in the parent process do NOT propagate
+    to subagent processes spawned by Claude Code's Task() tool.
+
+    Strategy:
+    1. Query for task_delegation events with status='started' (not yet completed)
+    2. If found within the last 5 minutes, we're likely in a subagent context
+    3. Return the subagent_type and parent session info
+
+    Args:
+        db: HtmlGraphDB instance
+        current_session_id: The session_id from hook_input (Claude Code's session ID)
+
+    Returns:
+        Tuple of (subagent_type, parent_session_id, parent_event_id)
+        All None if not in subagent context
+    """
+    try:
+        if db.connection is None:
+            return None, None, None
+
+        cursor = db.connection.cursor()
+
+        # Query for active task_delegation events (started but not completed)
+        # that were created in the last 5 minutes
+        # Exclude events that belong to the current session (those are parent context, not subagent)
+        cursor.execute(
+            """
+            SELECT event_id, session_id, subagent_type, timestamp
+            FROM agent_events
+            WHERE event_type = 'task_delegation'
+            AND status = 'started'
+            AND timestamp >= datetime('now', '-5 minutes')
+            AND session_id != ?
+            ORDER BY timestamp DESC
+            LIMIT 1
+            """,
+            (current_session_id,),
+        )
+        row = cursor.fetchone()
+
+        if row:
+            parent_event_id = row[0]
+            parent_session_id = row[1]
+            subagent_type = row[2] or "general-purpose"
+
+            print(
+                f"Debug: Detected subagent context from database: "
+                f"type={subagent_type}, parent_session={parent_session_id}, "
+                f"parent_event={parent_event_id}",
+                file=sys.stderr,
+            )
+
+            return subagent_type, parent_session_id, parent_event_id
+
+        return None, None, None
+
+    except Exception as e:
+        print(
+            f"Debug: Error detecting subagent context from database: {e}",
+            file=sys.stderr,
+        )
+        return None, None, None
+
+
 def extract_file_paths(tool_input: dict[str, Any], tool_name: str) -> list[str]:
     """Extract file paths from tool input based on tool type."""
     paths = []
@@ -543,6 +614,7 @@ def record_event_to_sqlite(
     agent_id: str | None = None,
     subagent_type: str | None = None,
     model: str | None = None,
+    feature_id: str | None = None,
 ) -> str | None:
     """
     Record a tool call event to SQLite database for dashboard queries.
@@ -559,6 +631,7 @@ def record_event_to_sqlite(
         agent_id: Agent identifier (optional)
         subagent_type: Subagent type for Task delegations (optional)
         model: Claude model name (e.g., claude-haiku, claude-opus) (optional)
+        feature_id: Feature ID for attribution (optional)
 
     Returns:
         event_id if successful, None otherwise
@@ -603,6 +676,7 @@ def record_event_to_sqlite(
             cost_tokens=0,
             subagent_type=subagent_type,
             model=model,
+            feature_id=feature_id,
         )
 
         if success:
@@ -710,19 +784,43 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
         detected_model = model_from_input
 
     active_session = None
+    is_subagent_session = False
+    parent_event_id_for_session = None
+
+    # Get session_id from hook_input first (Claude Code provides this)
+    hook_session_id = hook_input.get("session_id") or hook_input.get("sessionId")
 
-    # 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
+    # Check if we're in a subagent context using multiple methods:
+    # Method 1: Environment variables (works if Task() spawner sets them)
     subagent_type = os.environ.get("HTMLGRAPH_SUBAGENT_TYPE")
     parent_session_id = os.environ.get("HTMLGRAPH_PARENT_SESSION")
 
+    # Method 2: Database-based detection (CRITICAL for Claude Code Task() tool)
+    # Environment variables don't propagate to subagent processes, so we check
+    # the database for active task_delegation events
+    if not subagent_type and db and hook_session_id:
+        db_subagent_type, db_parent_session_id, db_parent_event_id = (
+            detect_subagent_context_from_database(db, hook_session_id)
+        )
+        if db_subagent_type:
+            subagent_type = db_subagent_type
+            parent_session_id = db_parent_session_id
+            parent_event_id_for_session = db_parent_event_id
+            print(
+                f"Debug: Using database-based subagent detection: "
+                f"type={subagent_type}, parent={parent_session_id}",
+                file=sys.stderr,
+            )
+
     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}"
+        # We're in a subagent context
+        is_subagent_session = True
 
-        # Check if subagent session already exists
+        # Use Claude's session_id (hook_session_id) as the subagent session ID
+        # This ensures events are properly tracked to this session
+        subagent_session_id = hook_session_id or f"{parent_session_id}-{subagent_type}"
+
+        # Check if session already exists in our system
         existing = manager.session_converter.load(subagent_session_id)
         if existing:
             active_session = existing
@@ -742,7 +840,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                 )
                 print(
                     f"Debug: Created subagent session: {subagent_session_id} "
-                    f"(parent: {parent_session_id})",
+                    f"(parent: {parent_session_id}, is_subagent=True)",
                     file=sys.stderr,
                 )
             except Exception as e:
@@ -755,18 +853,38 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
         # 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}
+        # Normal orchestrator/parent context
+        # CRITICAL: Use session_id from hook_input (Claude Code provides this)
+        # Only fall back to manager.get_active_session() if not in hook_input
+        if hook_session_id:
+            # Claude Code provided session_id - use it directly
+            # Check if session already exists
+            existing = manager.session_converter.load(hook_session_id)
+            if existing:
+                active_session = existing
+            else:
+                # Create new session with Claude's session_id
+                try:
+                    active_session = manager.start_session(
+                        session_id=hook_session_id,
+                        agent=detected_agent,
+                        title=f"Session {datetime.now().strftime('%Y-%m-%d %H:%M')}",
+                    )
+                except Exception:
+                    return {"continue": True}
+        else:
+            # Fallback: No session_id in hook_input - use global session cache
+            active_session = manager.get_active_session()
+            if not active_session:
+                # No active HtmlGraph session yet; start one
+                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
 
@@ -786,10 +904,13 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                 except Exception:
                     return default
 
+            # Use is_subagent_session flag from our detection, not just from session object
             is_subagent_raw = safe_getattr(active_session, "is_subagent", False)
-            is_subagent = (
+            is_subagent_from_obj = (
                 bool(is_subagent_raw) if isinstance(is_subagent_raw, bool) else False
             )
+            # Prefer our detection (is_subagent_session) over object attribute
+            final_is_subagent = is_subagent_session or is_subagent_from_obj
 
             transcript_id = safe_getattr(active_session, "transcript_id", None)
             transcript_path = safe_getattr(active_session, "transcript_path", None)
@@ -799,14 +920,35 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
             if transcript_path is not None and not isinstance(transcript_path, str):
                 transcript_path = None
 
+            # Get parent_session_id from our detection or from session object
+            final_parent_session_id = parent_session_id or safe_getattr(
+                active_session, "parent_session_id", None
+            )
+            if final_parent_session_id is not None and not isinstance(
+                final_parent_session_id, str
+            ):
+                final_parent_session_id = None
+
             db.insert_session(
                 session_id=active_session_id,
                 agent_assigned=safe_getattr(active_session, "agent", None)
                 or detected_agent,
-                is_subagent=is_subagent,
+                parent_session_id=final_parent_session_id,
+                parent_event_id=parent_event_id_for_session,
+                is_subagent=final_is_subagent,
                 transcript_id=transcript_id,
                 transcript_path=transcript_path,
             )
+
+            # Log subagent session creation for debugging
+            if final_is_subagent:
+                print(
+                    f"Debug: Inserted subagent session to SQLite: "
+                    f"session_id={active_session_id}, is_subagent=True, "
+                    f"parent_session={final_parent_session_id}, "
+                    f"parent_event={parent_event_id_for_session}",
+                    file=sys.stderr,
+                )
         except Exception as e:
             # Session may already exist, that's OK - continue
             print(
@@ -818,7 +960,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
     if hook_type == "Stop":
         # Session is ending - track stop event
         try:
-            manager.track_activity(
+            result = manager.track_activity(
                 session_id=active_session_id, tool="Stop", summary="Agent stopped"
             )
 
@@ -833,6 +975,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     is_error=False,
                     agent_id=detected_agent,
                     model=detected_model,
+                    feature_id=result.feature_id if result else None,
                 )
         except Exception as e:
             print(f"Warning: Could not track stop: {e}", file=sys.stderr)
@@ -846,7 +989,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
             preview += "..."
 
         try:
-            manager.track_activity(
+            result = manager.track_activity(
                 session_id=active_session_id, tool="UserQuery", summary=f'"{preview}"'
             )
 
@@ -863,6 +1006,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     is_error=False,
                     agent_id=detected_agent,
                     model=detected_model,
+                    feature_id=result.feature_id if result else None,
                 )
 
         except Exception as e:
@@ -915,20 +1059,29 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
         warning_threshold = drift_settings.get("warning_threshold") or 0.7
         auto_classify_threshold = drift_settings.get("auto_classify_threshold") or 0.85
 
-        # Determine parent activity context using database-only lookup
+        # Determine parent activity context using multiple sources
         parent_activity_id = None
 
-        # Check environment variable FIRST for cross-process parent linking
+        # Priority 1: If we're in a subagent context, use the parent event from
+        # the task_delegation that spawned us (detected from database)
+        if is_subagent_session and parent_event_id_for_session:
+            parent_activity_id = parent_event_id_for_session
+            print(
+                f"Debug: Using parent_event from subagent detection: {parent_activity_id}",
+                file=sys.stderr,
+            )
+        # Priority 2: Check environment variable for cross-process parent linking
         # This is set by PreToolUse hook when Task() spawns a subagent
-        env_parent = os.environ.get("HTMLGRAPH_PARENT_EVENT") or os.environ.get(
-            "HTMLGRAPH_PARENT_QUERY_EVENT"
-        )
-        if env_parent:
-            parent_activity_id = env_parent
-        # Query database for most recent UserQuery event as parent
-        # Database is the single source of truth for parent-child linking
-        elif db:
-            parent_activity_id = get_parent_user_query(db, active_session_id)
+        else:
+            env_parent = os.environ.get("HTMLGRAPH_PARENT_EVENT") or os.environ.get(
+                "HTMLGRAPH_PARENT_QUERY_EVENT"
+            )
+            if env_parent:
+                parent_activity_id = env_parent
+            # Priority 3: Query database for most recent UserQuery event as parent
+            # Database is the single source of truth for parent-child linking
+            elif db:
+                parent_activity_id = get_parent_user_query(db, active_session_id)
 
         # Track the activity
         nudge = None
@@ -963,6 +1116,7 @@ def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
                     agent_id=detected_agent,
                     subagent_type=task_subagent_type,
                     model=detected_model,
+                    feature_id=result.feature_id if result else None,
                 )
 
             # If this was a Task() delegation, also record to agent_collaboration

htmlgraph/hooks/git_commands.py

@@ -0,0 +1,175 @@
+"""
+Shared git command classification for hooks.
+
+Provides consistent rules for which git operations are allowed vs require delegation.
+Used by both validator.py and orchestrator.py to ensure consistent behavior.
+"""
+
+from typing import Literal
+
+GitCommandType = Literal["read", "write", "unknown"]
+
+# Read-only git commands (safe to allow)
+GIT_READ_ONLY = {
+    "status",
+    "log",
+    "diff",
+    "show",
+    "branch",  # When used with -l or --list or no args
+    "reflog",
+    "ls-files",
+    "ls-remote",
+    "rev-parse",
+    "describe",
+    "tag",  # When used without -a/-d or with -l
+    "remote",  # When used with -v or show
+}
+
+# Write operations (require delegation)
+GIT_WRITE_OPS = {
+    "add",
+    "commit",
+    "push",
+    "pull",
+    "fetch",
+    "merge",
+    "rebase",
+    "cherry-pick",
+    "reset",
+    "checkout",  # Can modify working tree
+    "switch",
+    "restore",
+    "rm",
+    "mv",
+    "clean",
+    "stash",
+}
+
+
+def classify_git_command(command: str) -> GitCommandType:
+    """
+    Classify a git command as read, write, or unknown.
+
+    Args:
+        command: Full command string (e.g., "git status" or "git add .")
+
+    Returns:
+        "read", "write", or "unknown"
+
+    Examples:
+        >>> classify_git_command("git status")
+        "read"
+        >>> classify_git_command("git commit -m 'msg'")
+        "write"
+        >>> classify_git_command("git log --oneline")
+        "read"
+        >>> classify_git_command("git add .")
+        "write"
+    """
+    # Strip "git" prefix and get subcommand
+    parts = command.strip().split()
+    if not parts or parts[0] != "git":
+        return "unknown"
+
+    if len(parts) < 2:
+        return "unknown"
+
+    subcommand = parts[1]
+
+    # Check write operations first (more critical)
+    if subcommand in GIT_WRITE_OPS:
+        return "write"
+
+    # Special handling for branch (flag-based classification)
+    if subcommand == "branch":
+        # branch with -d or -D flags is write, otherwise read
+        if len(parts) > 2:
+            flags = " ".join(parts[2:])
+            if (
+                " -d " in flags
+                or " -D " in flags
+                or flags.startswith("-d ")
+                or flags.startswith("-D ")
+            ):
+                return "write"
+        return "read"
+
+    # Special handling for tag (flag-based classification)
+    if subcommand == "tag":
+        # tag with -a (annotated) or -d (delete) flags is write, otherwise read
+        if len(parts) > 2:
+            flags = " ".join(parts[2:])
+            if (
+                " -a " in flags
+                or " -d " in flags
+                or flags.startswith("-a ")
+                or flags.startswith("-d ")
+            ):
+                return "write"
+        return "read"
+
+    # Then check read-only
+    if subcommand in GIT_READ_ONLY:
+        return "read"
+
+    # Unknown git command
+    return "unknown"
+
+
+def should_allow_git_command(command: str) -> bool:
+    """
+    Check if a git command should be allowed without delegation.
+
+    Returns:
+        True if command is read-only (safe), False if write (delegate)
+
+    Examples:
+        >>> should_allow_git_command("git status")
+        True
+        >>> should_allow_git_command("git commit -m 'msg'")
+        False
+        >>> should_allow_git_command("git diff HEAD~1")
+        True
+        >>> should_allow_git_command("git push origin main")
+        False
+    """
+    cmd_type = classify_git_command(command)
+    return cmd_type == "read"
+
+
+def get_git_delegation_reason(command: str) -> str:
+    """
+    Get delegation reason for git write operations.
+
+    Args:
+        command: Git command that requires delegation
+
+    Returns:
+        Human-readable reason explaining why delegation is required
+    """
+    parts = command.strip().split()
+    if len(parts) < 2:
+        return "Git write operations should be delegated to Skill('.claude-plugin:copilot')"
+
+    subcommand = parts[1]
+
+    if subcommand in ["commit", "add", "push"]:
+        return (
+            f"Git {subcommand} is a write operation and should be delegated to "
+            f"Skill('.claude-plugin:copilot') for proper Git workflow management"
+        )
+    elif subcommand in ["merge", "rebase", "cherry-pick"]:
+        return (
+            f"Git {subcommand} is a complex merge operation and should be delegated to "
+            f"Skill('.claude-plugin:copilot') for safe execution"
+        )
+    elif subcommand in ["reset", "checkout", "restore"]:
+        return (
+            f"Git {subcommand} can modify working tree and should be delegated to "
+            f"Skill('.claude-plugin:copilot') for safe execution"
+        )
+    else:
+        return (
+            f"Git {subcommand} is a write operation and should be delegated to "
+            f"Skill('.claude-plugin:copilot')"
+        )