refactor: simplify agent update logic with clearer conditionals

Refactor _ensure_plugins_loaded to use explicit has_mcp_config flag
and direct self._plugin_specs checks instead of the agent_update_needed
flag. This provides clearer intent while maintaining correctness and
proper type safety.

The agent update is now conditionally executed only when there are
plugins or MCP config to process, avoiding unnecessary model_copy
calls that could interfere with agent initialization.

Also adds comments explaining the keyword-only * syntax (PEP 3102)
in expand_mcp_variables and load_mcp_config functions to prevent
ambiguous positional boolean arguments.

Per review feedback from @neubig.

Author: openhands-agent

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -332,6 +332,9 @@ def _ensure_plugins_loaded(self) -> None:
         merged_context = self.agent.agent_context
         merged_mcp = dict(self.agent.mcp_config) if self.agent.mcp_config else {}
 
+        # Track whether we have plugins or MCP config to process
+        has_mcp_config = bool(merged_mcp)
+
         # Load plugins if specified
         if self._plugin_specs:
             logger.info(f"Loading {len(self._plugin_specs)} plugin(s)...")
@@ -359,6 +362,7 @@ def _ensure_plugins_loaded(self) -> None:
                 # Merge plugin contents
                 merged_context = plugin.add_skills_to(merged_context)
                 merged_mcp = plugin.add_mcp_config_to(merged_mcp)
+                has_mcp_config = has_mcp_config or bool(merged_mcp)
 
                 # Collect hooks
                 if plugin.hooks and not plugin.hooks.is_empty():
@@ -387,17 +391,19 @@ def _ensure_plugins_loaded(self) -> None:
             else:
                 logger.debug("Applied MCP config defaults (no secrets provided)")
 
-        # Update agent with merged content (context from plugins, expanded MCP config)
-        self.agent = self.agent.model_copy(
-            update={
-                "agent_context": merged_context,
-                "mcp_config": merged_mcp,
-            }
-        )
+        # Update agent with merged content only if we have plugins or MCP config
+        # Skip update when nothing changed to avoid unnecessary agent state mutations
+        if self._plugin_specs or has_mcp_config:
+            self.agent = self.agent.model_copy(
+                update={
+                    "agent_context": merged_context,
+                    "mcp_config": merged_mcp,
+                }
+            )
 
-        # Also update the agent in _state so API responses reflect loaded plugins
-        with self._state:
-            self._state.agent = self.agent
+            # Also update the agent in _state so API responses reflect loaded plugins
+            with self._state:
+                self._state.agent = self.agent
 
         # Register file-based agents defined in plugins
         if all_plugin_agents:

openhands-sdk/openhands/sdk/skills/utils.py

@@ -69,7 +69,7 @@ def expand_mcp_variables(
     config: dict,
     variables: dict[str, str],
     secrets: dict[str, str] | None = None,
-    *,
+    *,  # no positional booleans (PEP 3102)
     expand_defaults: bool = True,
 ) -> dict:
     """Expand variables in MCP configuration.
@@ -128,7 +128,7 @@ def load_mcp_config(
     mcp_json_path: Path,
     skill_root: Path | None = None,
     secrets: dict[str, str] | None = None,
-    *,
+    *,  # no positional booleans (PEP 3102)
     expand_defaults: bool = True,
 ) -> dict:
     """Load and parse .mcp.json with variable expansion.