Method RunShell

pkg/tools/builtin/shell/shell.go:230–261

(ctx context.Context, params RunShellArgs)

}

func (h *shellHandler) RunShell(ctx context.Context, params RunShellArgs) (*tools.ToolCallResult, error) {
	if strings.TrimSpace(params.Cmd) == "" {
		return tools.ResultError(`Error: missing or empty "cmd" parameter. Pass the shell command as {"cmd": "..."}.`), nil
	}

	timeout := h.timeout
	if params.Timeout > 0 {
		timeout = time.Duration(params.Timeout) * time.Second
	}

	timeoutCtx, cancel := context.WithTimeout(ctx, timeout)
	defer cancel()

	cwd := h.resolveWorkDir(params.Cwd)

	// Stamp the call shape (cmd, cwd, timeout) onto the active span.
	// Cmd ships unconditionally — it's the main signal of what the
	// agent actually did, and gating it on chat-content capture loses
	// too much debug value. Drop or hash `cagent.tool.shell.cmd` at
	// the OTel collector if commands routinely carry secrets.
	if span := trace.SpanFromContext(ctx); span.IsRecording() {
		span.SetAttributes(
			attribute.String("cagent.tool.shell.cmd", params.Cmd),
			attribute.Float64("cagent.tool.shell.timeout_seconds", timeout.Seconds()),
			attribute.String("cagent.tool.shell.cwd", cwd),
		)
	}

	slog.DebugContext(ctx, "Executing native shell command", "command", params.Cmd, "cwd", cwd)

	return h.runNativeCommand(timeoutCtx, ctx, params.Cmd, cwd, timeout), nil
}

// waitDelayAfterShellExit caps how long cmd.Wait() blocks on stdout/stderr
// copy goroutines after the direct shell child has exited.