From f4562b8f9d74e01ac0342bd5d5f45ddfe7390e77 Mon Sep 17 00:00:00 2001 From: Vincenzo Palazzo Date: Tue, 28 Jul 2026 10:49:35 +0200 Subject: [PATCH] docs: document auto-injected GOOSE_SHELL flags The shell flags goose injects based on shell type (-NoProfile -NonInteractive -Command for PowerShell, /C for cmd, -c for POSIX shells) were undocumented. A PR reviewer noted they searched the docs expecting to add these flags manually, only to find they are injected automatically. - Fix a misplaced doc comment on windows_shell() that described Unix shell behavior (Flatpak, basename auto-detection) instead of Windows - Add a doc comment to build_shell_command() documenting the automatic flag mapping for PowerShell/cmd/POSIX shells - Add a user-facing note in the environment-variables guide Co-Authored-By: goose --- .../platform_extensions/developer/shell.rs | 24 ++++++++++++++----- .../docs/guides/environment-variables.md | 9 +++++++ 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/crates/goose/src/agents/platform_extensions/developer/shell.rs b/crates/goose/src/agents/platform_extensions/developer/shell.rs index 7c3bbaff1588..15fc5542f689 100644 --- a/crates/goose/src/agents/platform_extensions/developer/shell.rs +++ b/crates/goose/src/agents/platform_extensions/developer/shell.rs @@ -84,13 +84,13 @@ fn unix_shell_command_args(command_line: &str) -> [&str; 2] { ["-c", command_line] } -/// Resolve the preferred Unix shell for command execution, respecting GOOSE_SHELL. -/// -/// Auto-detected shells are returned as basenames (e.g. `"bash"`) so that -/// `Command::new` resolves them on `PATH` at spawn time — this also keeps -/// Flatpak happy, where absolute paths from inside the sandbox don't match -/// the host filesystem. `GOOSE_SHELL` is passed through as-is. +/// Resolve the shell used to run Developer extension commands on Windows, +/// respecting `GOOSE_SHELL`. /// +/// Defaults to `cmd` when `GOOSE_SHELL` is unset. The invocation flags are +/// chosen automatically from the executable name in `build_shell_command`, +/// so callers only ever provide a bare executable path or name — see that +/// function for the flag mapping. #[cfg(windows)] fn windows_shell() -> String { std::env::var("GOOSE_SHELL").unwrap_or_else(|_| "cmd".to_string()) @@ -624,6 +624,18 @@ async fn run_command( }) } +/// Build the `Command` that executes a single command line via the configured shell. +/// +/// The invocation flags are selected automatically from the shell executable +/// name, so setting `GOOSE_SHELL` to a bare executable is enough — users never +/// need to supply command-style flags themselves: +/// +/// - PowerShell (`pwsh`, `powershell`) → `-NoProfile -NonInteractive -Command` +/// - cmd (`cmd`) → `/C` +/// - POSIX shells (bash, zsh, … via Cygwin/MSYS2) → `-c` +/// +/// On Unix the default shell (`bash`, falling back to `sh`) is likewise invoked +/// as ` -c `. fn build_shell_command( command_line: &str, working_dir: Option<&std::path::Path>, diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index 3dbd125f4ecf..a6a50deba630 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -312,6 +312,15 @@ REM Windows: use a POSIX-like shell instead of cmd.exe set GOOSE_SHELL=C:\cygwin64\bin\bash.exe ``` +:::note +You only ever set `GOOSE_SHELL` to a shell executable path or name. goose injects the command-line flags automatically based on the shell, so there is no need to add them yourself: + +- **PowerShell** (`pwsh`, `powershell`) → `-NoProfile -NonInteractive -Command` +- **cmd** → `/C` +- **POSIX shells** (bash, zsh, … on Windows via Cygwin/MSYS2) → `-c` +- On Unix the default shell (`bash`, falling back to `sh`) is invoked as ` -c` +::: + ## Security and Privacy These variables control security features, credential storage, and anonymous usage data collection.