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

htmlgraph/hooks/event_tracker.py

@@ -5,12 +5,17 @@ Reusable event tracking logic for hook integrations.
 Provides session management, drift detection, activity logging, and SQLite persistence.
 
 Public API:
-    track_event(hook_type: str, tool_input: dict) -> dict
+    track_event(hook_type: str, tool_input: dict[str, Any]) -> dict
         Main entry point for tracking hook events (PostToolUse, Stop, UserPromptSubmit)
 
 Events are recorded to both:
     - HTML files via SessionManager (existing)
     - SQLite database via HtmlGraphDB (new - for dashboard queries)
+
+Parent-child event linking:
+    - Database is the single source of truth for parent-child linking
+    - UserQuery events are stored in agent_events table with tool_name='UserQuery'
+    - get_parent_user_query() queries database for most recent UserQuery in session
 """
 
 import json
@@ -20,7 +25,7 @@ import subprocess
 import sys
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, cast
+from typing import Any, cast  # noqa: F401
 
 from htmlgraph.db.schema import HtmlGraphDB
 from htmlgraph.ids import generate_id
@@ -28,18 +33,50 @@ from htmlgraph.session_manager import SessionManager
 
 # Drift classification queue (stored in session directory)
 DRIFT_QUEUE_FILE = "drift-queue.json"
-# Active parent activity tracker (for Skill/Task invocations)
-PARENT_ACTIVITY_FILE = "parent-activity.json"
-# UserQuery event tracker (for parent-child linking) - DEPRECATED (use session-scoped files)
-USER_QUERY_EVENT_FILE = "user-query-event.json"
 
 
-def get_user_query_event_file(graph_dir: Path, session_id: str) -> Path:
-    """Get the session-scoped user query event file path."""
-    return graph_dir / f"user-query-event-{session_id}.json"
+def get_model_from_status_cache(session_id: str | None = None) -> str | None:
+    """
+    Read current model from SQLite model_cache table.
+
+    The status line script writes model info to the model_cache table.
+    This allows hooks to know which Claude model is currently running,
+    even though hooks don't receive model info directly from Claude Code.
+
+    Args:
+        session_id: Unused, kept for backward compatibility.
+
+    Returns:
+        Model display name (e.g., "Opus 4.5", "Sonnet", "Haiku") or None if not found.
+    """
+    import sqlite3
+
+    try:
+        # Try project database first
+        db_path = Path.cwd() / ".htmlgraph" / "htmlgraph.db"
+        if not db_path.exists():
+            return None
+
+        conn = sqlite3.connect(str(db_path), timeout=1.0)
+        cursor = conn.cursor()
+
+        # Check if model_cache table exists and has data
+        cursor.execute("SELECT model FROM model_cache WHERE id = 1 LIMIT 1")
+        row = cursor.fetchone()
+        conn.close()
+
+        if row and row[0] and row[0] != "Claude":
+            return str(row[0])
+        return str(row[0]) if row else None
+
+    except Exception:
+        # Table doesn't exist or read error - silently fail
+        pass
+
+    return None
 
 
-def load_drift_config() -> dict:
+def load_drift_config() -> dict[str, Any]:
     """Load drift configuration from plugin config or project .claude directory."""
     config_paths = [
         Path(__file__).parent.parent.parent.parent.parent
@@ -80,110 +117,46 @@ def load_drift_config() -> dict:
     }
 
 
-def load_parent_activity(graph_dir: Path) -> dict:
-    """Load the active parent activity state."""
-    path = graph_dir / PARENT_ACTIVITY_FILE
-    if path.exists():
-        try:
-            with open(path) as f:
-                data = cast(dict[Any, Any], json.load(f))
-                # Clean up stale parent activities (older than 5 minutes)
-                if data.get("timestamp"):
-                    ts = datetime.fromisoformat(data["timestamp"])
-                    # Use timezone-aware datetime for comparison
-                    now = datetime.now(timezone.utc)
-                    # Ensure ts is timezone-aware (handle both formats)
-                    if ts.tzinfo is None:
-                        ts = ts.replace(tzinfo=timezone.utc)
-                    if now - ts > timedelta(minutes=5):
-                        return {}
-                return data
-        except Exception:
-            pass
-    return {}
-
-
-def save_parent_activity(
-    graph_dir: Path, parent_id: str | None, tool: str | None = None
-) -> None:
-    """Save the active parent activity state."""
-    path = graph_dir / PARENT_ACTIVITY_FILE
-    try:
-        if parent_id:
-            with open(path, "w") as f:
-                json.dump(
-                    {
-                        "parent_id": parent_id,
-                        "tool": tool,
-                        "timestamp": datetime.now(timezone.utc).isoformat(),
-                    },
-                    f,
-                )
-        else:
-            # Clear parent activity
-            path.unlink(missing_ok=True)
-    except Exception as e:
-        print(f"Warning: Could not save parent activity: {e}", file=sys.stderr)
-
-
-def load_user_query_event(graph_dir: Path, session_id: str) -> str | None:
+def get_parent_user_query(db: HtmlGraphDB, session_id: str) -> str | None:
     """
-    Load the active UserQuery event ID for parent-child linking.
-
-    Session-scoped: Each session maintains its own parent context via
-    user-query-event-{SESSION_ID}.json to support multiple concurrent
-    Claude windows in the same project.
-    """
-    path = get_user_query_event_file(graph_dir, session_id)
-    if path.exists():
-        try:
-            with open(path) as f:
-                data = cast(dict[Any, Any], json.load(f))
-                # Clean up stale UserQuery events (older than 10 minutes)
-                if data.get("timestamp"):
-                    ts = datetime.fromisoformat(data["timestamp"])
-                    now = datetime.now(timezone.utc)
-                    if ts.tzinfo is None:
-                        ts = ts.replace(tzinfo=timezone.utc)
-                    # UserQuery events expire after 10 minutes (conversation turn boundary)
-                    # This allows tool calls up to 10 minutes after a user query to be linked as children
-                    if now - ts > timedelta(minutes=10):
-                        return None
-                return data.get("event_id")
-        except Exception:
-            pass
-    return None
+    Get the most recent UserQuery event_id for this session from database.
 
+    This is the primary method for parent-child event linking.
+    Database is the single source of truth - no file-based state.
 
-def save_user_query_event(
-    graph_dir: Path, session_id: str, event_id: str | None
-) -> None:
-    """
-    Save the active UserQuery event ID for parent-child linking.
+    Args:
+        db: HtmlGraphDB instance
+        session_id: Session ID to query
 
-    Session-scoped: Each session maintains its own parent context via
-    user-query-event-{SESSION_ID}.json to support multiple concurrent
-    Claude windows in the same project.
+    Returns:
+        event_id of the most recent UserQuery event, or None if not found
     """
-    path = get_user_query_event_file(graph_dir, session_id)
     try:
-        if event_id:
-            with open(path, "w") as f:
-                json.dump(
-                    {
-                        "event_id": event_id,
-                        "timestamp": datetime.now(timezone.utc).isoformat(),
-                    },
-                    f,
-                )
-        else:
-            # Clear UserQuery event
-            path.unlink(missing_ok=True)
+        if db.connection is None:
+            return None
+        cursor = db.connection.cursor()
+        cursor.execute(
+            """
+            SELECT event_id FROM agent_events
+            WHERE session_id = ? AND tool_name = 'UserQuery'
+            ORDER BY timestamp DESC
+            LIMIT 1
+            """,
+            (session_id,),
+        )
+        row = cursor.fetchone()
+        if row:
+            return str(row[0])
+        return None
     except Exception as e:
-        print(f"Warning: Could not save UserQuery event: {e}", file=sys.stderr)
+        print(
+            f"Debug: Database query for UserQuery failed: {e}",
+            file=sys.stderr,
+        )
+        return None
 
 
-def load_drift_queue(graph_dir: Path, max_age_hours: int = 48) -> dict:
+def load_drift_queue(graph_dir: Path, max_age_hours: int = 48) -> dict[str, Any]:
     """
     Load the drift queue from file and clean up stale entries.
 
@@ -232,7 +205,7 @@ def load_drift_queue(graph_dir: Path, max_age_hours: int = 48) -> dict:
     return {"activities": [], "last_classification": None}
 
 
-def save_drift_queue(graph_dir: Path, queue: dict) -> None:
+def save_drift_queue(graph_dir: Path, queue: dict[str, Any]) -> None:
     """Save the drift queue to file."""
     queue_path = graph_dir / DRIFT_QUEUE_FILE
     try:
@@ -266,7 +239,9 @@ def clear_drift_queue_activities(graph_dir: Path) -> None:
         print(f"Warning: Could not clear drift queue: {e}", file=sys.stderr)
 
 
-def add_to_drift_queue(graph_dir: Path, activity: dict, config: dict) -> dict:
+def add_to_drift_queue(
+    graph_dir: Path, activity: dict[str, Any], config: dict[str, Any]
+) -> dict[str, Any]:
     """Add a high-drift activity to the queue."""
     max_age_hours = config.get("queue", {}).get("max_age_hours", 48)
     queue = load_drift_queue(graph_dir, max_age_hours=max_age_hours)
@@ -289,7 +264,9 @@ def add_to_drift_queue(graph_dir: Path, activity: dict, config: dict) -> dict:
     return queue
 
 
-def should_trigger_classification(queue: dict, config: dict) -> bool:
+def should_trigger_classification(
+    queue: dict[str, Any], config: dict[str, Any]
+) -> bool:
     """Check if we should trigger auto-classification."""
     drift_config = config.get("drift_detection", {})
 
@@ -316,7 +293,7 @@ def should_trigger_classification(queue: dict, config: dict) -> bool:
     return True
 
 
-def build_classification_prompt(queue: dict, feature_id: str) -> str:
+def build_classification_prompt(queue: dict[str, Any], feature_id: str) -> str:
     """Build the prompt for the classification agent."""
     activities = queue.get("activities", [])
 
@@ -368,41 +345,108 @@ def resolve_project_path(cwd: str | None = None) -> str:
     return start_dir
 
 
-def detect_agent_from_environment() -> str:
+def detect_model_from_hook_input(hook_input: dict[str, Any]) -> str | None:
     """
-    Detect the agent/model name from environment variables.
+    Detect the Claude model from hook input data.
+
+    Checks in order of priority:
+    1. Task() model parameter (if tool_name == 'Task')
+    2. HTMLGRAPH_MODEL environment variable (set by hooks)
+    3. ANTHROPIC_MODEL or CLAUDE_MODEL environment variables
 
-    Checks multiple environment variables in order of priority:
+    Args:
+        hook_input: Hook input dict containing tool_name and tool_input
+
+    Returns:
+        Model name (e.g., 'claude-opus', 'claude-sonnet', 'claude-haiku') or None
+    """
+    # Get tool info
+    tool_name_value: Any = hook_input.get("tool_name", "") or hook_input.get("name", "")
+    tool_name = tool_name_value if isinstance(tool_name_value, str) else ""
+    tool_input_value: Any = hook_input.get("tool_input", {}) or hook_input.get(
+        "input", {}
+    )
+    tool_input = tool_input_value if isinstance(tool_input_value, dict) else {}
+
+    # 1. Check for Task() model parameter first
+    if tool_name == "Task" and "model" in tool_input:
+        model_value: Any = tool_input.get("model")
+        if model_value and isinstance(model_value, str):
+            model = model_value.strip().lower()
+            if model:
+                if not model.startswith("claude-"):
+                    model = f"claude-{model}"
+                return cast(str, model)
+
+    # 2. Check environment variables (set by PreToolUse hook)
+    for env_var in ["HTMLGRAPH_MODEL", "ANTHROPIC_MODEL", "CLAUDE_MODEL"]:
+        value = os.environ.get(env_var)
+        if value and isinstance(value, str):
+            model = value.strip()
+            if model:
+                return model
+
+    return None
+
+
+def detect_agent_from_environment() -> tuple[str, str | None]:
+    """
+    Detect the agent/model name from environment variables and status cache.
+
+    Checks multiple sources in order of priority:
     1. HTMLGRAPH_AGENT - Explicit agent name set by user
     2. HTMLGRAPH_SUBAGENT_TYPE - For subagent sessions
-    3. CLAUDE_MODEL - Model name if exposed by Claude Code
-    4. ANTHROPIC_MODEL - Alternative model env var
-    5. HTMLGRAPH_PARENT_AGENT - Parent agent context
+    3. HTMLGRAPH_PARENT_AGENT - Parent agent context
+    4. HTMLGRAPH_MODEL - Model name (e.g., claude-haiku, claude-opus)
+    5. CLAUDE_MODEL - Model name if exposed by Claude Code
+    6. ANTHROPIC_MODEL - Alternative model env var
+    7. Status line cache (model only) - ~/.cache/claude-code/status-{session_id}.json
 
     Falls back to 'claude-code' if no environment variable is set.
 
     Returns:
-        Agent/model identifier string
+        Tuple of (agent_id, model_name). Model name may be None if not detected.
     """
-    # Check environment variables in priority order
-    env_vars = [
+    # Check for explicit agent name first
+    agent_id = None
+    env_vars_agent = [
         "HTMLGRAPH_AGENT",
         "HTMLGRAPH_SUBAGENT_TYPE",
+        "HTMLGRAPH_PARENT_AGENT",
+    ]
+
+    for var in env_vars_agent:
+        value = os.environ.get(var)
+        if value and value.strip():
+            agent_id = value.strip()
+            break
+
+    # Check for model name separately
+    model_name = None
+    env_vars_model = [
+        "HTMLGRAPH_MODEL",
         "CLAUDE_MODEL",
         "ANTHROPIC_MODEL",
-        "HTMLGRAPH_PARENT_AGENT",
     ]
 
-    for var in env_vars:
+    for var in env_vars_model:
         value = os.environ.get(var)
         if value and value.strip():
-            return value.strip()
+            model_name = value.strip()
+            break
+
+    # Fallback: Try to read model from status line cache
+    if not model_name:
+        model_name = get_model_from_status_cache()
+
+    # Default fallback for agent_id
+    if not agent_id:
+        agent_id = "claude-code"
 
-    # Default fallback
-    return "claude-code"
+    return agent_id, model_name
 
 
-def extract_file_paths(tool_input: dict, tool_name: str) -> list[str]:
+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 = []
 
@@ -427,7 +471,7 @@ def extract_file_paths(tool_input: dict, tool_name: str) -> list[str]:
 
 
 def format_tool_summary(
-    tool_name: str, tool_input: dict, tool_result: dict | None = None
+    tool_name: str, tool_input: dict[str, Any], tool_result: dict | None = None
 ) -> str:
     """Format a human-readable summary of the tool call."""
     if tool_name == "Read":
@@ -491,13 +535,14 @@ def record_event_to_sqlite(
     db: HtmlGraphDB,
     session_id: str,
     tool_name: str,
-    tool_input: dict,
-    tool_response: dict,
+    tool_input: dict[str, Any],
+    tool_response: dict[str, Any],
     is_error: bool,
     file_paths: list[str] | None = None,
     parent_event_id: str | None = None,
     agent_id: str | None = None,
     subagent_type: str | None = None,
+    model: str | None = None,
 ) -> str | None:
     """
     Record a tool call event to SQLite database for dashboard queries.
@@ -513,6 +558,7 @@ def record_event_to_sqlite(
         parent_event_id: Parent event ID if this is a child event
         agent_id: Agent identifier (optional)
         subagent_type: Subagent type for Task delegations (optional)
+        model: Claude model name (e.g., claude-haiku, claude-opus) (optional)
 
     Returns:
         event_id if successful, None otherwise
@@ -523,7 +569,7 @@ def record_event_to_sqlite(
 
         # Build output summary from tool response
         output_summary = ""
-        if isinstance(tool_response, dict):
+        if isinstance(tool_response, dict):  # type: ignore[arg-type]
             if is_error:
                 output_summary = tool_response.get("error", "error")[:200]
             else:
@@ -556,6 +602,7 @@ def record_event_to_sqlite(
             parent_event_id=parent_event_id,
             cost_tokens=0,
             subagent_type=subagent_type,
+            model=model,
         )
 
         if success:
@@ -573,7 +620,7 @@ def record_delegation_to_sqlite(
     from_agent: str,
     to_agent: str,
     task_description: str,
-    task_input: dict,
+    task_input: dict[str, Any],
 ) -> str | None:
     """
     Record a Task() delegation to agent_collaboration table.
@@ -619,7 +666,7 @@ def record_delegation_to_sqlite(
         return None
 
 
-def track_event(hook_type: str, hook_input: dict) -> dict:
+def track_event(hook_type: str, hook_input: dict[str, Any]) -> dict[str, Any]:
     """
     Track a hook event and log it to HtmlGraph (both HTML files and SQLite).
 
@@ -652,8 +699,13 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
         print(f"Warning: Could not initialize SQLite database: {e}", file=sys.stderr)
         # Continue without SQLite (graceful degradation)
 
-    # Detect agent from environment
-    detected_agent = detect_agent_from_environment()
+    # Detect agent and model from environment
+    detected_agent, detected_model = detect_agent_from_environment()
+
+    # Also try to detect model from hook input (more specific than environment)
+    model_from_input = detect_model_from_hook_input(hook_input)
+    if model_from_input:
+        detected_model = model_from_input
 
     # Get active session ID
     active_session = manager.get_active_session()
@@ -732,6 +784,7 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                     tool_response={"content": "Agent stopped"},
                     is_error=False,
                     agent_id=detected_agent,
+                    model=detected_model,
                 )
         except Exception as e:
             print(f"Warning: Could not track stop: {e}", file=sys.stderr)
@@ -749,10 +802,11 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                 session_id=active_session_id, tool="UserQuery", summary=f'"{preview}"'
             )
 
-            # Record to SQLite if available and capture event_id for parent-child linking
-            user_query_event_id = None
+            # Record to SQLite if available
+            # UserQuery event is stored in database - no file-based state needed
+            # Subsequent tool calls query database for parent via get_parent_user_query()
             if db:
-                user_query_event_id = record_event_to_sqlite(
+                record_event_to_sqlite(
                     db=db,
                     session_id=active_session_id,
                     tool_name="UserQuery",
@@ -760,14 +814,9 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                     tool_response={"content": "Query received"},
                     is_error=False,
                     agent_id=detected_agent,
+                    model=detected_model,
                 )
 
-                # Store the UserQuery event_id for subsequent tool calls to use as parent
-                if user_query_event_id:
-                    save_user_query_event(
-                        graph_dir, active_session_id, user_query_event_id
-                    )
-
         except Exception as e:
             print(f"Warning: Could not track query: {e}", file=sys.stderr)
         return {"continue": True}
@@ -792,7 +841,7 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
         summary = format_tool_summary(tool_name, tool_input_data, tool_response)
 
         # Determine success
-        if isinstance(tool_response, dict):
+        if isinstance(tool_response, dict):  # type: ignore[arg-type]
             success_field = tool_response.get("success")
             if isinstance(success_field, bool):
                 is_error = not success_field
@@ -818,37 +867,20 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
         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
-        parent_activity_state = load_parent_activity(graph_dir)
+        # Determine parent activity context using database-only lookup
         parent_activity_id = None
 
-        # Tools that create parent context (Skill, Task)
-        parent_tools = {"Skill", "Task"}
-
-        # If this is a parent tool invocation, save its context for subsequent activities
-        if tool_name in parent_tools:
-            # We'll get the event_id after tracking, so we use a placeholder for now
-            # The actual parent_id will be set below after we track the activity
-            is_parent_tool = True
-        else:
-            is_parent_tool = False
-            # Check environment variable FIRST for cross-process parent linking
-            # This is set by PreToolUse hook when Task() spawns a subagent
-            env_parent = os.environ.get("HTMLGRAPH_PARENT_EVENT")
-            if env_parent:
-                parent_activity_id = env_parent
-            # Next, check for UserQuery event as parent (for prompt-based grouping)
-            # UserQuery takes priority over parent_activity_json to ensure each conversation turn
-            # has its tool calls properly grouped together
-            else:
-                user_query_event_id = load_user_query_event(
-                    graph_dir, active_session_id
-                )
-                if user_query_event_id:
-                    parent_activity_id = user_query_event_id
-                # Fall back to parent-activity.json only if no UserQuery event (backward compatibility)
-                elif parent_activity_state.get("parent_id"):
-                    parent_activity_id = parent_activity_state["parent_id"]
+        # Check environment variable FIRST 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)
 
         # Track the activity
         nudge = None
@@ -882,6 +914,7 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                     parent_event_id=parent_activity_id,  # Link to parent event
                     agent_id=detected_agent,
                     subagent_type=task_subagent_type,
+                    model=detected_model,
                 )
 
             # If this was a Task() delegation, also record to agent_collaboration
@@ -897,12 +930,6 @@ def track_event(hook_type: str, hook_input: dict) -> dict:
                     task_input=tool_input_data,
                 )
 
-            # If this was a parent tool, save its ID for subsequent activities
-            if is_parent_tool and result:
-                save_parent_activity(graph_dir, result.id, tool_name)
-            # If this tool finished a parent context (e.g., Task completed), clear it
-            # We'll clear parent context after 5 minutes automatically (see load_parent_activity)
-
             # Check for drift and handle accordingly
             # Skip drift detection for child activities (they inherit parent's context)
             if result and hasattr(result, "drift_score") and not parent_activity_id:

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)