feat: Support short options and positional arguments in RunSkillScriptTool

  - Updates `parameters_json_schema` to accept `short_options` (object) and `positional_args` (array).
  - Updates `_SkillScriptCodeExecutor._build_wrapper_code` to materialize these options for both Python and Shell scripts.
  - Appends `--` before positional arguments to remove ambiguity in CLI parsing.
  - Adds comprehensive unit tests.

PiperOrigin-RevId: 895536577
Change-Id: I834b2a6f6965e0a17aa8e208966cbe7a88c3428f

Author: google-genai-bot

src/google/adk/tools/skill_toolset.py

@@ -510,8 +510,15 @@ def _build_wrapper_code(
 
     if ext == "py":
       argv_list = [script_path]
-      for k, v in script_args.items():
+      for k, v in script_args.get("args", {}).items():
         argv_list.extend([f"--{k}", str(v)])
+      for k, v in script_args.get("short_options", {}).items():
+        argv_list.extend([f"-{k}", str(v)])
+      positional_args = script_args.get("positional_args", [])
+      if positional_args:
+        argv_list.append("--")
+        for v in positional_args:
+          argv_list.append(str(v))
       code_lines.extend([
           f"      sys.argv = {argv_list!r}",
           "      try:",
@@ -522,8 +529,15 @@ def _build_wrapper_code(
       ])
     elif ext in ("sh", "bash"):
       arr = ["bash", script_path]
-      for k, v in script_args.items():
+      for k, v in script_args.get("args", {}).items():
         arr.extend([f"--{k}", str(v)])
+      for k, v in script_args.get("short_options", {}).items():
+        arr.extend([f"-{k}", str(v)])
+      positional_args = script_args.get("positional_args", [])
+      if positional_args:
+        arr.append("--")
+        for v in positional_args:
+          arr.append(str(v))
       timeout = self._script_timeout
       code_lines.extend([
           "      try:",
@@ -590,8 +604,23 @@ def _get_declaration(self) -> types.FunctionDeclaration | None:
                 "args": {
                     "type": "object",
                     "description": (
-                        "Optional arguments to pass to the script as key-value"
-                        " pairs."
+                        "Optional arguments to pass as long options (e.g.,"
+                        " {'n': 5} becomes --n 5)."
+                    ),
+                },
+                "short_options": {
+                    "type": "object",
+                    "description": (
+                        "Optional SHORT options to pass (e.g., {'n': 5}"
+                        " becomes -n 5)."
+                    ),
+                },
+                "positional_args": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": (
+                        "Optional list of positional arguments in exact order"
+                        " (e.g., ['input.txt', 'output.txt'])."
                     ),
                 },
             },
@@ -604,16 +633,38 @@ async def run_async(
   ) -> Any:
     skill_name = args.get("skill_name")
     script_path = args.get("script_path")
-    script_args = args.get("args", {})
-    if not isinstance(script_args, dict):
+    script_args = {
+        "args": args.get("args", {}),
+        "short_options": args.get("short_options", {}),
+        "positional_args": args.get("positional_args", []),
+    }
+    if not isinstance(script_args["args"], dict):
       return {
           "error": (
               "'args' must be a JSON object (key-value pairs),"
-              f" got {type(script_args).__name__}."
+              f" got {type(script_args['args']).__name__}."
           ),
           "error_code": "INVALID_ARGS_TYPE",
       }
 
+    if not isinstance(script_args["short_options"], dict):
+      return {
+          "error": (
+              "'short_options' must be a JSON object (key-value pairs),"
+              f" got {type(script_args['short_options']).__name__}."
+          ),
+          "error_code": "INVALID_SHORT_OPTIONS_TYPE",
+      }
+
+    if not isinstance(script_args["positional_args"], list):
+      return {
+          "error": (
+              "'positional_args' must be a JSON array (list),"
+              f" got {type(script_args['positional_args']).__name__}."
+          ),
+          "error_code": "INVALID_POSITIONAL_ARGS_TYPE",
+      }
+
     if not skill_name:
       return {
           "error": "Skill name is required.",

tests/unittests/tools/test_skill_toolset.py

@@ -653,6 +653,61 @@ async def test_execute_script_with_input_args_shell(mock_skill1):
   assert "['bash', 'scripts/setup.sh', '--force', 'True']" in code_input.code
 
 
+@pytest.mark.asyncio
+async def test_execute_script_with_short_options_and_positional_args_python(
+    mock_skill1,
+):
+  executor = _make_mock_executor(stdout="done\n")
+  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",
+          "script_path": "run.py",
+          "args": {"verbose": True},
+          "short_options": {"n": "5"},
+          "positional_args": ["input.txt"],
+      },
+      tool_context=ctx,
+  )
+  assert result["status"] == "success"
+
+  call_args = executor.execute_code.call_args
+  code_input = call_args[0][1]
+  assert (
+      "['scripts/run.py', '--verbose', 'True', '-n', '5', '--', 'input.txt']"
+      in code_input.code
+  )
+
+
+@pytest.mark.asyncio
+async def test_execute_script_with_short_options_and_positional_args_shell(
+    mock_skill1,
+):
+  executor = _make_mock_executor(stdout="done\n")
+  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",
+          "script_path": "setup.sh",
+          "short_options": {"n": "5"},
+          "positional_args": ["input.txt"],
+      },
+      tool_context=ctx,
+  )
+  assert result["status"] == "success"
+
+  call_args = executor.execute_code.call_args
+  code_input = call_args[0][1]
+  assert (
+      "['bash', 'scripts/setup.sh', '-n', '5', '--', 'input.txt']"
+      in code_input.code
+  )
+
+
 @pytest.mark.asyncio
 async def test_execute_script_scripts_prefix_stripping(mock_skill1):
   executor = _make_mock_executor(stdout="setup\n")
@@ -1244,6 +1299,66 @@ async def test_execute_script_invalid_args_type(mock_skill1, bad_args):
   executor.execute_code.assert_not_called()
 
 
+@pytest.mark.parametrize(
+    "bad_short_options",
+    [
+        "not a dict",
+        42,
+        True,
+        ["list"],
+    ],
+)
+@pytest.mark.asyncio
+async def test_execute_script_invalid_short_options_type(
+    mock_skill1, bad_short_options
+):
+  """Non-dict short_options should return INVALID_SHORT_OPTIONS_TYPE, not crash."""
+  executor = _make_mock_executor()
+  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",
+          "script_path": "run.py",
+          "short_options": bad_short_options,
+      },
+      tool_context=ctx,
+  )
+  assert result["error_code"] == "INVALID_SHORT_OPTIONS_TYPE"
+  executor.execute_code.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "bad_positional_args",
+    [
+        "not a list",
+        42,
+        True,
+        {"dict": 1},
+    ],
+)
+@pytest.mark.asyncio
+async def test_execute_script_invalid_positional_args_type(
+    mock_skill1, bad_positional_args
+):
+  """Non-list positional_args should return INVALID_POSITIONAL_ARGS_TYPE, not crash."""
+  executor = _make_mock_executor()
+  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",
+          "script_path": "run.py",
+          "positional_args": bad_positional_args,
+      },
+      tool_context=ctx,
+  )
+  assert result["error_code"] == "INVALID_POSITIONAL_ARGS_TYPE"
+  executor.execute_code.assert_not_called()
+
+
 # ── Finding 4: binary file content is handled in wrapper ──