fix: decode shell skill output as UTF-8

VectorPeak · wukath · copybara-github · commit b7ad76a28dfb · 2026-07-15T11:52:59.000-07:00
Merge #6288 ## Summary - Decode shell skill output as UTF-8 to keep it independent from host locale. - Preserve shell exit code with stderr output. Closes #6289 ## Testing - Activated virtual environment in open_source_workspace. - Ran `pytest tests/unittests/tools/test_skill_toolset.py`. - 113 tests passed. Co-authored-by: Kathy Wu <wukathy@google.com> PiperOrigin-RevId: 948464268
diff --git a/src/google/adk/tools/skill_toolset.py b/src/google/adk/tools/skill_toolset.py
@@ -564,8 +564,13 @@ async def execute_script_async(
             stdout = parsed.get("stdout", "")
             stderr = parsed.get("stderr", "")
             rc = parsed.get("returncode", 0)
-            if rc != 0 and not stderr:
-              stderr = f"Exit code {rc}"
+            if rc != 0 and not parsed.get("timeout", False):
+              exit_code_message = f"Exit code {rc}"
+              stderr = (
+                  f"{stderr.rstrip()}\n{exit_code_message}"
+                  if stderr
+                  else exit_code_message
+              )
         except (json.JSONDecodeError, ValueError):
           pass
 
@@ -745,6 +750,8 @@ def _build_wrapper_code(
           "        _r = subprocess.run(",
           f"          {arr!r},",
           "          capture_output=True, text=True,",
+          # Keep shell output decoding independent from the host locale.
+          "          encoding='utf-8', errors='replace',",
           f"          timeout={timeout!r}, cwd=td,",
           "        )",
           "        print(_json.dumps({",
@@ -759,6 +766,7 @@ def _build_wrapper_code(
           "            'stdout': _e.stdout or '',",
           f"            'stderr': 'Timed out after {timeout}s',",
           "            'returncode': -1,",
+          "            'timeout': True,",
           "        }))",
       ])
     else:
diff --git a/tests/unittests/tools/test_skill_toolset.py b/tests/unittests/tools/test_skill_toolset.py
@@ -15,6 +15,7 @@
 
 import asyncio
 import collections
+import json
 import logging
 import sys
 from unittest import mock
@@ -996,6 +997,8 @@ async def test_execute_script_shell_success(mock_skill1):
   code_input = call_args[0][1]
   assert "subprocess.run" in code_input.code
   assert "bash" in code_input.code
+  assert "encoding='utf-8'" in code_input.code
+  assert "errors='replace'" in code_input.code
   assert "__shell_result__" in code_input.code
 
 
@@ -1583,7 +1586,6 @@ async def test_integration_shell_stderr_only():
 @pytest.mark.asyncio
 async def test_shell_json_envelope_parsed(mock_skill1):
   """Shell JSON envelope is correctly unpacked by run_async."""
-  import json
 
   envelope = json.dumps({
       "__shell_result__": True,
@@ -1607,7 +1609,6 @@ async def test_shell_json_envelope_parsed(mock_skill1):
 @pytest.mark.asyncio
 async def test_shell_json_envelope_nonzero_returncode(mock_skill1):
   """Non-zero returncode in shell envelope sets stderr."""
-  import json
 
   envelope = json.dumps({
       "__shell_result__": True,
@@ -1627,10 +1628,31 @@ async def test_shell_json_envelope_nonzero_returncode(mock_skill1):
   assert "Exit code 2" in result["stderr"]
 
 
+@pytest.mark.asyncio
+async def test_shell_json_envelope_nonzero_returncode_with_stderr(mock_skill1):
+  """Non-zero returncode in shell envelope appends exit code to stderr."""
+
+  envelope = json.dumps({
+      "__shell_result__": True,
+      "stdout": "",
+      "stderr": "some error occurred",
+      "returncode": 2,
+  })
+  executor = _make_mock_executor(stdout=envelope)
+  toolset = skill_toolset.SkillToolset([mock_skill1], code_executor=executor)
+  tool = skill_toolset.RunSkillScriptTool(toolset)
+  ctx = _make_tool_context_with_agent()
+  result = await tool.run_async(
+      args={"skill_name": "skill1", "file_path": "setup.sh"},
+      tool_context=ctx,
+  )
+  assert result["status"] == "error"
+  assert result["stderr"] == "some error occurred\nExit code 2"
+
+
 @pytest.mark.asyncio
 async def test_shell_json_envelope_with_stderr(mock_skill1):
   """Shell envelope with both stdout and stderr reports warning."""
-  import json
 
   envelope = json.dumps({
       "__shell_result__": True,
@@ -1654,13 +1676,13 @@ async def test_shell_json_envelope_with_stderr(mock_skill1):
 @pytest.mark.asyncio
 async def test_shell_json_envelope_timeout(mock_skill1):
   """Shell envelope from TimeoutExpired reports error status."""
-  import json
 
   envelope = json.dumps({
       "__shell_result__": True,
       "stdout": "partial output\n",
       "stderr": "Timed out after 300s",
       "returncode": -1,
+      "timeout": True,
   })
   executor = _make_mock_executor(stdout=envelope)
   toolset = skill_toolset.SkillToolset([mock_skill1], code_executor=executor)
@@ -1673,6 +1695,7 @@ async def test_shell_json_envelope_timeout(mock_skill1):
   assert result["status"] == "error"
   assert result["stdout"] == "partial output\n"
   assert "Timed out" in result["stderr"]
+  assert "Exit code" not in result["stderr"]
 
 
 @pytest.mark.asyncio
