From c5b91639677f2f025138985d87e8bba2e7021d02 Mon Sep 17 00:00:00 2001
From: Rizel Scarlett <rizel@squareup.com>
Date: Mon, 29 Dec 2025 17:35:09 -0500
Subject: [PATCH] docs: clarify GOOSE_TERMINAL requires ~/.zshenv for zsh users
 (#6297)

---
 .../docs/guides/environment-variables.md      | 21 +++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md
index 6e270075..927aca4e 100644
--- a/documentation/docs/guides/environment-variables.md
+++ b/documentation/docs/guides/environment-variables.md
@@ -419,17 +419,30 @@ These variables are automatically set by goose during command execution.
 
 ### Customizing Shell Behavior
 
-Sometimes you want goose to use different commands or have different shell behavior than your normal terminal usage. For example, you might want goose to use a different tool, or prevent goose from running long-running development servers that could hang the AI agent. This is most useful when using goose CLI, where shell commands are executed directly in your terminal environment.
+Sometimes you want goose to use different commands or have different shell behavior than your normal terminal usage. For example, you might want goose to use a different tool, prevent goose from running `git commit`, or block long-running development servers that could hang the AI agent. This is most useful when using goose CLI, where shell commands are executed directly in your terminal environment.
 
 **How it works:**
 1. When goose runs commands, `GOOSE_TERMINAL` is automatically set to "1"
-2. Your shell configuration can detect this and direct goose to change its default behavior while keeping your normal terminal usage unchanged
+2. Your shell configuration can detect this and change behavior while keeping your normal terminal usage unchanged
 
-**Example:**
+**Examples:**
 
 ```bash
-# In your ~/.bashrc or ~/.zshrc
+# In ~/.zshenv (for zsh users) or ~/.bashrc (for bash users)
 
+# Block git commit when run by goose
+if [[ -n "$GOOSE_TERMINAL" ]]; then
+  git() {
+    if [[ "$1" == "commit" ]]; then
+      echo "❌ BLOCKED: git commit is not allowed when run by goose"
+      return 1
+    fi
+    command git "$@"
+  }
+fi
+```
+
+```bash
 # Guide goose toward better tool choices
 if [[ -n "$GOOSE_TERMINAL" ]]; then
   alias find="echo 'Use rg instead: rg --files | rg <pattern> for filenames, or rg <pattern> for content search'"