Shell Tool Environment Variable Support

Objective

Add environment variable support to the shell tool, allowing agents to specify environment variable names that should be set before executing commands. The infrastructure will read these environment variables from the system and apply them during command execution.

Implementation Plan

Task 1. Update Shell Tool Domain Model
Extend the Shell struct in crates/forge_domain/src/tools.rs to include an optional env field that accepts a vector of environment variable names. This field will specify which environment variables should be passed to the command execution environment.
Task 2. Update CommandInfra Interface
Modify the CommandInfra trait in crates/forge_services/src/infra.rs to accept environment variable names in the execute_command and execute_command_raw methods. This involves adding a new parameter env_vars: Option<Vec<String>> to both methods.
Task 3. Update ShellService Interface
Extend the ShellService trait in crates/forge_app/src/services.rs to accept environment variable names in the execute method. Add env_vars: Option<Vec<String>> parameter to maintain consistency with the updated CommandInfra interface.
Task 4. Update Shell Service Implementation
Modify the ForgeShell implementation in crates/forge_services/src/tool_services/shell.rs to pass environment variable names to the infrastructure layer. Update the execute method to forward the env_vars parameter to the command infrastructure.
Task 5. Update Command Executor Implementation
Enhance the ForgeCommandExecutorService in crates/forge_infra/src/executor.rs to read specified environment variables from the system and apply them to the command execution context. Modify the prepare_command method to set the requested environment variables on the Command instance.
Task 6. Update Tool Operation Processing
Modify the shell tool operation handling in crates/forge_app/src/operation.rs and crates/forge_app/src/tool_executor.rs to extract environment variable names from the Shell tool input and pass them through the service chain.
Task 7. Update Infrastructure Implementations
Update all CommandInfra implementations to support the new environment variable parameter, including the main implementation in crates/forge_infra/src/forge_infra.rs and any test implementations in crates/forge_services/src/attachment.rs.
Task 8. Add Comprehensive Test Coverage
Create tests to verify environment variable functionality works correctly, including tests for missing environment variables, empty env lists, and successful environment variable application during command execution.

Verification Criteria

Environment variable names can be specified in shell tool calls through the new env field
Specified environment variables are properly read from the system and applied to command execution
Commands execute successfully with the requested environment variables available
Missing environment variables are handled gracefully without causing command failures
All existing shell tool functionality continues to work unchanged
Test suite passes with comprehensive coverage of the new environment variable feature

Potential Risks and Mitigations

Breaking API Changes
Mitigation: Use optional parameters and default values to maintain backward compatibility with existing shell tool usage
Environment Variable Security
Mitigation: Only read specified environment variables by name rather than exposing the entire environment to prevent unintended information leakage
Missing Environment Variables
Mitigation: Handle missing environment variables gracefully by either skipping them or providing clear error messages, depending on the desired behavior
Performance Impact
Mitigation: Only read environment variables when explicitly requested, avoiding unnecessary system calls when the env field is not provided

Alternative Approaches

Direct Environment Variable Values: Allow agents to specify environment variable values directly instead of just names
- Trade-offs: More flexible but potentially less secure, as it would allow agents to set arbitrary values rather than using system-defined values
Environment Variable Validation: Implement allowlists or validation for which environment variables can be accessed
- Trade-offs: Enhanced security but increased complexity and potential limitations for legitimate use cases
Separate Environment Tool: Create a dedicated tool for environment variable management instead of extending the shell tool
- Trade-offs: Cleaner separation of concerns but additional complexity for users who need both shell execution and environment variable access