From d2dd28203417d52090b8bb77fa5e832daa8c0b17 Mon Sep 17 00:00:00 2001
From: saurav470 <sauravsharma3001@gmail.com>
Date: Tue, 17 Feb 2026 01:40:07 +0530
Subject: [PATCH] docs(exec): document pty for TTY-only CLIs (gog)

---
 docs/tools/exec.md                    | 15 ++++++++++++++-
 src/agents/bash-tools.exec-runtime.ts |  2 +-
 src/agents/bash-tools.exec.ts         |  2 +-
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/tools/exec.md b/docs/tools/exec.md
index 70770af9f6f..201bebc4815 100644
--- a/docs/tools/exec.md
+++ b/docs/tools/exec.md
@@ -20,7 +20,7 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 - `yieldMs` (default 10000): auto-background after delay
 - `background` (bool): background immediately
 - `timeout` (seconds, default 1800): kill on expiry
-- `pty` (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)
+- `pty` (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs). Use for CLIs that only print when stdout is a TTY (e.g. gog / Google Workspace CLI).
 - `host` (`sandbox | gateway | node`): where to execute
 - `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`
 - `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`
@@ -42,6 +42,19 @@ Notes:
   the gateway host (no container) and **does not require approvals**. To require approvals, run with
   `host=gateway` and configure exec approvals (or enable sandboxing).
 
+### TTY-only CLIs (e.g. gog)
+
+Some CLIs write to stdout only when it is a TTY. In non-interactive contexts (exec tool, scripts, CI)
+they exit with code 0 but produce no output. Examples: **gog** (Google Workspace CLI), and other
+tools that use `isatty(stdout)` to decide whether to print. For these, set **`pty: true`** so the
+command runs in a pseudo-terminal and output is captured.
+
+Example:
+
+```json
+{ "tool": "exec", "command": "gog --version", "pty": true }
+```
+
 ## Config
 
 - `tools.exec.notifyOnExit` (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
diff --git a/src/agents/bash-tools.exec-runtime.ts b/src/agents/bash-tools.exec-runtime.ts
index d458df01d1e..1ef07b311aa 100644
--- a/src/agents/bash-tools.exec-runtime.ts
+++ b/src/agents/bash-tools.exec-runtime.ts
@@ -116,7 +116,7 @@ export const execSchema = Type.Object({
   pty: Type.Optional(
     Type.Boolean({
       description:
-        "Run in a pseudo-terminal (PTY) when available (TTY-required CLIs, coding agents)",
+        "Run in a pseudo-terminal (PTY) when available (TTY-required CLIs e.g. gog, coding agents)",
     }),
   ),
   elevated: Type.Optional(
diff --git a/src/agents/bash-tools.exec.ts b/src/agents/bash-tools.exec.ts
index e0fba6ea2b6..972560b9271 100644
--- a/src/agents/bash-tools.exec.ts
+++ b/src/agents/bash-tools.exec.ts
@@ -242,7 +242,7 @@ export function createExecTool(
     name: "exec",
     label: "exec",
     description:
-      "Execute shell commands with background continuation. Use yieldMs/background to continue later via process tool. Use pty=true for TTY-required commands (terminal UIs, coding agents).",
+      "Execute shell commands with background continuation. Use yieldMs/background to continue later via process tool. Use pty=true for TTY-required commands (e.g. gog, terminal UIs, coding agents).",
     parameters: execSchema,
     execute: async (_toolCallId, args, signal, onUpdate) => {
       const params = args as {