shell: accept "command" as alias for "cmd" and improve empty-arg error

Some models (notably Claude, biased by Anthropic's built-in bash tool and
other ecosystems using `command`) occasionally emit {"command": "..."}
instead of the schema's canonical {"cmd": "..."}. The tool then
rejected the call with "Error: empty command", wasting a turn before
the model retried with the right key.

This change:

- Adds a custom UnmarshalJSON on RunShellArgs and RunShellBackgroundArgs
  that accepts both "cmd" (canonical) and "command" (alias). "cmd"
  wins when both are present. The advertised JSON schema is unchanged.
- Rewrites the empty-command error to name the expected parameter so the
  model can self-correct without guessing.
- Also validates params.Cmd in RunShellBackground for parity with RunShell.
- Adds unit tests covering the alias path (both struct-level and
  end-to-end through the handler) and the actionable error message.

Refs #2478

Author: trungutt

pkg/tools/builtin/shell.go

@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"cmp"
 	"context"
+	"encoding/json"
 	"errors"
 	"fmt"
 	"log/slog"
@@ -102,11 +103,51 @@ type RunShellArgs struct {
 	Timeout int    `json:"timeout,omitempty" jsonschema:"Command execution timeout in seconds (default: 30)"`
 }
 
+// UnmarshalJSON accepts both the canonical "cmd" key and the common alias
+// "command" for the shell command parameter.
+//
+// The advertised schema still declares "cmd" as the canonical name, but many
+// models (particularly ones biased by Anthropic's built-in bash tool and other
+// ecosystems that use "command") occasionally emit "command" instead. Accepting
+// both prevents a wasted turn on an empty-command error while keeping the
+// canonical contract unchanged. When both keys are present, "cmd" wins.
+func (a *RunShellArgs) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Cmd     string `json:"cmd"`
+		Command string `json:"command"`
+		Cwd     string `json:"cwd"`
+		Timeout int    `json:"timeout"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	a.Cmd = cmp.Or(raw.Cmd, raw.Command)
+	a.Cwd = raw.Cwd
+	a.Timeout = raw.Timeout
+	return nil
+}
+
 type RunShellBackgroundArgs struct {
 	Cmd string `json:"cmd" jsonschema:"The shell command to execute in the background"`
 	Cwd string `json:"cwd,omitempty" jsonschema:"The working directory to execute the command in (default: \".\")"`
 }
 
+// UnmarshalJSON accepts both "cmd" (canonical) and "command" (common alias),
+// mirroring RunShellArgs.UnmarshalJSON. See its comment for rationale.
+func (a *RunShellBackgroundArgs) UnmarshalJSON(data []byte) error {
+	var raw struct {
+		Cmd     string `json:"cmd"`
+		Command string `json:"command"`
+		Cwd     string `json:"cwd"`
+	}
+	if err := json.Unmarshal(data, &raw); err != nil {
+		return err
+	}
+	a.Cmd = cmp.Or(raw.Cmd, raw.Command)
+	a.Cwd = raw.Cwd
+	return nil
+}
+
 type ViewBackgroundJobArgs struct {
 	JobID string `json:"job_id" jsonschema:"The ID of the background job to view"`
 }
@@ -132,7 +173,7 @@ func statusToString(status int32) string {
 
 func (h *shellHandler) RunShell(ctx context.Context, params RunShellArgs) (*tools.ToolCallResult, error) {
 	if strings.TrimSpace(params.Cmd) == "" {
-		return tools.ResultError("Error: empty command"), nil
+		return tools.ResultError(`Error: missing or empty "cmd" parameter. Pass the shell command as {"cmd": "..."}.`), nil
 	}
 
 	timeout := h.timeout
@@ -211,6 +252,10 @@ func (h *shellHandler) runNativeCommand(timeoutCtx, ctx context.Context, command
 }
 
 func (h *shellHandler) RunShellBackground(_ context.Context, params RunShellBackgroundArgs) (*tools.ToolCallResult, error) {
+	if strings.TrimSpace(params.Cmd) == "" {
+		return tools.ResultError(`Error: missing or empty "cmd" parameter. Pass the shell command as {"cmd": "..."}.`), nil
+	}
+
 	counter := h.jobCounter.Add(1)
 	jobID := fmt.Sprintf("job_%d_%d", time.Now().Unix(), counter)
 

pkg/tools/builtin/shell_test.go

@@ -1,6 +1,7 @@
 package builtin
 
 import (
+	"encoding/json"
 	"os"
 	"os/exec"
 	"runtime"
@@ -55,6 +56,90 @@ func TestShellTool_HandlerWithCwd(t *testing.T) {
 	assert.Contains(t, result.Output, tmpDir)
 }
 
+func TestRunShellArgs_UnmarshalJSON_AcceptsCmdAndCommand(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		input   string
+		wantCmd string
+		wantCwd string
+		wantTO  int
+	}{
+		{
+			name:    "canonical cmd",
+			input:   `{"cmd":"ls -la","cwd":"/tmp","timeout":10}`,
+			wantCmd: "ls -la",
+			wantCwd: "/tmp",
+			wantTO:  10,
+		},
+		{
+			name:    "alias command",
+			input:   `{"command":"ls -la","cwd":"/tmp","timeout":10}`,
+			wantCmd: "ls -la",
+			wantCwd: "/tmp",
+			wantTO:  10,
+		},
+		{
+			name:    "both present cmd wins",
+			input:   `{"cmd":"from-cmd","command":"from-command"}`,
+			wantCmd: "from-cmd",
+		},
+		{
+			name:    "empty object leaves cmd empty",
+			input:   `{}`,
+			wantCmd: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			var got RunShellArgs
+			require.NoError(t, json.Unmarshal([]byte(tt.input), &got))
+			assert.Equal(t, tt.wantCmd, got.Cmd)
+			assert.Equal(t, tt.wantCwd, got.Cwd)
+			assert.Equal(t, tt.wantTO, got.Timeout)
+		})
+	}
+}
+
+func TestRunShellBackgroundArgs_UnmarshalJSON_AcceptsCmdAndCommand(t *testing.T) {
+	t.Parallel()
+
+	var viaCmd RunShellBackgroundArgs
+	require.NoError(t, json.Unmarshal([]byte(`{"cmd":"sleep 1","cwd":"/tmp"}`), &viaCmd))
+	assert.Equal(t, "sleep 1", viaCmd.Cmd)
+	assert.Equal(t, "/tmp", viaCmd.Cwd)
+
+	var viaCommand RunShellBackgroundArgs
+	require.NoError(t, json.Unmarshal([]byte(`{"command":"sleep 1"}`), &viaCommand))
+	assert.Equal(t, "sleep 1", viaCommand.Cmd)
+}
+
+// Exercises the end-to-end dispatch path: a tool-call whose raw arguments
+// use "command" instead of "cmd" must execute normally rather than return
+// the missing-parameter error.
+func TestShellTool_HandlerAcceptsCommandAlias(t *testing.T) {
+	tool := NewShellTool(nil, &config.RuntimeConfig{Config: config.Config{WorkingDir: t.TempDir()}})
+
+	var params RunShellArgs
+	require.NoError(t, json.Unmarshal([]byte(`{"command":"echo hello-from-alias"}`), &params))
+
+	result, err := tool.handler.RunShell(t.Context(), params)
+	require.NoError(t, err)
+	assert.Contains(t, result.Output, "hello-from-alias")
+}
+
+func TestShellTool_HandlerMissingCmdReturnsActionableError(t *testing.T) {
+	tool := NewShellTool(nil, &config.RuntimeConfig{Config: config.Config{WorkingDir: t.TempDir()}})
+
+	result, err := tool.handler.RunShell(t.Context(), RunShellArgs{})
+	require.NoError(t, err)
+	assert.Contains(t, result.Output, `"cmd"`,
+		"error must name the expected parameter so the model can self-correct")
+}
+
 func TestShellTool_HandlerError(t *testing.T) {
 	tool := NewShellTool(nil, &config.RuntimeConfig{Config: config.Config{WorkingDir: t.TempDir()}})