fix(mcp): consolidate header sanitization and clean up review findings

- Move sanitization from _get_auth_headers to _execute_with_session boundary
- Replace verbose _DANGEROUS_CHARS literal with frozenset comprehension
- Remove redundant CRLF strip already handled by sanitize_header_value
- Use lazy %-formatting instead of f-strings in logging
- Clarify docstrings for run() Optional new_message and from_config()

Author: timof1308

src/google/adk/runners.py

@@ -458,7 +458,9 @@ def run(
     Args:
       user_id: The user ID of the session.
       session_id: The session ID of the session.
-      new_message: A new message to append to the session.
+      new_message: An optional new message to append to the session. When
+        omitted, either an invocation_id must be provided to resume a
+        previous invocation, or the app must be configured as resumable.
       invocation_id: The invocation id to resume.
       state_delta: Optional state changes to apply to the session.
       request_state: Optional ephemeral state for the request.

src/google/adk/tools/mcp_tool/_internal.py

@@ -48,43 +48,9 @@
 # RFC 7230 compliant header name pattern (allows letters, digits, hyphens)
 _HEADER_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9-]+\Z")
 
-# Truly dangerous characters that should never appear in header values
-# These are characters that can break HTTP parsing or cause injection
-_DANGEROUS_CHARS = {
-    "\x00",
-    "\x01",
-    "\x02",
-    "\x03",
-    "\x04",
-    "\x05",
-    "\x06",
-    "\x07",
-    "\x08",
-    "\x09",
-    "\x0a",
-    "\x0b",
-    "\x0c",
-    "\x0d",
-    "\x0e",
-    "\x0f",
-    "\x10",
-    "\x11",
-    "\x12",
-    "\x13",
-    "\x14",
-    "\x15",
-    "\x16",
-    "\x17",
-    "\x18",
-    "\x19",
-    "\x1a",
-    "\x1b",
-    "\x1c",
-    "\x1d",
-    "\x1e",
-    "\x1f",
-    "\x7f",
-}
+# ASCII control characters (0x00-0x1F) and DEL (0x7F) that must never
+# appear in HTTP header values — prevents injection and response splitting.
+_DANGEROUS_CHARS = frozenset(chr(i) for i in range(0x20)) | frozenset({chr(0x7F)})
 
 
 def validate_header_name(header_name: str) -> None:

src/google/adk/tools/mcp_tool/mcp_toolset.py

@@ -163,10 +163,6 @@ def provider(ctx: ReadonlyContext) -> Dict[str, str]:
 
     validate_header_value(state_key, value, strict=strict)
     formatted_value = header_format.format(value=value)
-    # Defense in depth: strip CRLF before sanitization. sanitize_header_value
-    # also strips these, but we strip early to prevent injection via format
-    # string interpolation.
-    formatted_value = formatted_value.replace("\r", "").replace("\n", "")
     sanitized_value = sanitize_header_value(formatted_value)
 
     return {header_name: sanitized_value}
@@ -204,12 +200,13 @@ def combined_provider(ctx: ReadonlyContext) -> Dict[str, str]:
             )
           headers.update(provider_headers)
       except Exception as e:
-        logger.error(f"Header provider {i+1}/{num_providers} failed: {e}")
+        logger.error("Header provider %d/%d failed: %s", i + 1, num_providers, e)
         raise
 
     if headers:
       logger.debug(
-          f"Combined header provider generated {len(headers)} total headers"
+          "Combined header provider generated %d total headers",
+          len(headers),
       )
     return headers
 
@@ -444,10 +441,6 @@ def _get_auth_headers(
           # Default to using scheme name as header
           headers = {self._auth_config.auth_scheme.name: credential.api_key}
 
-    # Sanitize all header values to prevent injection attacks.
-    if headers:
-      headers = {k: sanitize_header_value(v) for k, v in headers.items()}
-
     return headers
 
   async def _execute_with_session(
@@ -470,6 +463,10 @@ async def _execute_with_session(
       if provider_headers:
         headers.update(provider_headers)
 
+    # Sanitize all header values at the boundary to prevent injection.
+    if headers:
+      headers = {k: sanitize_header_value(v) for k, v in headers.items()}
+
     session = await self._mcp_session_manager.create_session(
         headers=headers if headers else None
     )
@@ -611,7 +608,13 @@ def get_auth_config(self) -> Optional[AuthConfig]:
   def from_config(
       cls: type[McpToolset], config: ToolArgsConfig, config_abs_path: str
   ) -> McpToolset:
-    """Creates an McpToolset from a configuration object."""
+    """Creates an McpToolset from a configuration object.
+
+    Note: This method constructs the header_provider from the declarative
+    state_header_mapping in the config. Since McpToolsetConfig is a
+    serializable Pydantic model, it cannot hold callable objects. To use a
+    custom header_provider, construct McpToolset directly.
+    """
     mcp_toolset_config = McpToolsetConfig.model_validate(config.model_dump())
 
     if mcp_toolset_config.stdio_server_params: