From cd8ac459679e7979205af3b75e7fb13c3df23712 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Fri, 5 Jun 2026 12:34:12 -0600 Subject: [PATCH] docs: added explanation for the 2>/dev/tty for bash built-in script tool usage --- Bash-Prompt-Helpers.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/Bash-Prompt-Helpers.md b/Bash-Prompt-Helpers.md index 91b4794..900ee99 100644 --- a/Bash-Prompt-Helpers.md +++ b/Bash-Prompt-Helpers.md @@ -28,6 +28,27 @@ scripts: source "$LLM_PROMPT_UTILS_FILE" ``` +# Why Examples Use `2>/dev/tty` +Coyote runs each tool as a subprocess and **captures the tool's stderr** into a buffer. When the wrapped command exits +non-zero, that buffer is attached to the tool result returned to the LLM as `error_json["stderr"]`. + +All the interactive helpers below (`input`, `confirm`, `list`, `checkbox`, `password`, etc.) write their prompt text and +terminal escape sequences to stderr. Without redirection, the prompt leaks into the LLM-visible error JSON the next time +your tool exits non-zero, which can produce hallucinations where the model "sees" a confirmation prompt that was meant +for the user. + +**The fix is to send the helper's stderr straight to the user's terminal:** + +```bash +answer=$(confirm "Proceed?" 2>/dev/tty) +``` + +Helpers read user input from `/dev/tty` directly, so the redirect only affects the *output* (the prompt itself). Every +example below uses this pattern. Copy it as-is whenever you wrap a helper in `$(...)`. + +> `guard_operation` and `guard_path` already apply this redirect internally so you do **not** need `2>/dev/tty` when +> calling them. + # Included Utility Functions Below are the built-in bash prompt helpers that can be used to enhance user interaction with your tool scripts.