From 608d7e1b12ceff1942937980c63a6acb006ea563 Mon Sep 17 00:00:00 2001
From: dianed-square <73617011+dianed-square@users.noreply.github.com>
Date: Thu, 19 Feb 2026 12:12:09 -0800
Subject: [PATCH] docs: pass env vars to shell (#7361)

---
 .../docs/guides/environment-variables.md      |  6 ++++++
 documentation/docs/mcp/developer-mcp.md       | 19 ++++++++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index b522fe80e4..7ace4f8f33 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -671,6 +671,12 @@ echo "Results from step 1" > ~/Desktop/${AGENT_SESSION_ID}/handoff/output.txt
 cat ~/Desktop/${AGENT_SESSION_ID}/handoff/output.txt
 ```
 
+## Environment Variable Passthrough
+
+The Developer extension's `shell` tool inherits environment variables from your session. This enables workflows that depend on environment configuration, such as authenticated CLI operations and build processes.
+
+See [Environment Variables in Shell Commands](/docs/mcp/developer-mcp#environment-variables-in-shell-commands) for details.
+
 ## Enterprise Environments
 
 When deploying goose in enterprise environments, administrators might need to control behavior and infrastructure, or enforce consistent settings across teams. The following environment variables are commonly used:
diff --git a/documentation/docs/mcp/developer-mcp.md b/documentation/docs/mcp/developer-mcp.md
index a200c30e52..c7bed24457 100644
--- a/documentation/docs/mcp/developer-mcp.md
+++ b/documentation/docs/mcp/developer-mcp.md
@@ -172,6 +172,23 @@ The Developer extension provides these tools:
 | `screen_capture` | Take screenshots | Debugging UI issues, documenting state | ✅ Low<br />Visual information only |
 | `image_processor` | Process and resize images | Optimizing assets, format conversion | ✅ Low<br />Image manipulation only |
 
+### Environment Variables in Shell Commands
+
+Shell commands executed by the `shell` tool inherit the environment of the running goose process. This typically includes:
+- System variables like `PATH`, `HOME`, and `USER`
+- Environment variables present in the process that launched goose (for example, your terminal's environment when you start goose from a shell)
+- Session-specific variables injected by goose, such as `AGENT_SESSION_ID` for [session-isolated workflows](/docs/guides/environment-variables#using-session-ids-in-workflows)
+
+This enables workflows that depend on environment configuration, such as authenticated CLI operations and build processes.
+
+:::info
+goose Desktop or launcher-based starts may use a different environment and may not load your shell startup files.
+:::
+
+:::warning Sensitive Information
+Environment variables may contain sensitive values like API keys and tokens (e.g., `GITHUB_TOKEN`, `AWS_ACCESS_KEY_ID`).
+:::
+
 ### Access Control Features
 
 You can layer multiple controls to match your risk tolerance and workflow:
@@ -222,4 +239,4 @@ As you become more comfortable with goose's behavior, you can adjust these setti
 
 :::info
 Also see the [Security Guide](/docs/guides/security/) for information about using goose safely.
-:::
\ No newline at end of file
+:::