docs: added explicit mention to not add user interaction via custom tools or script nodes for graph execution

Graph-Agents.md

@@ -260,14 +260,14 @@ The temp file (when used) is cleaned up automatically after the graph finishes.
 Script nodes also receive the same environment that custom agent tools get when called
 from normal agents:
 
-| Env var                  | Contents                                                       |
+| Env var                         | Contents                                                       |
-|--------------------------|----------------------------------------------------------------|
+|---------------------------------|----------------------------------------------------------------|
-| `LLM_ROOT_DIR`           | Coyote config dir (e.g. `~/.config/coyote`)                        |
+| `LLM_ROOT_DIR`                  | Coyote config dir (e.g. `~/.config/coyote`)                    |
-| `LLM_PROMPT_UTILS_FILE`  | Absolute path to `.shared/prompt-utils.sh`                     |
+| `LLM_PROMPT_UTILS_FILE`         | Absolute path to `.shared/prompt-utils.sh`                     |
-| `LLM_AGENT_DATA_DIR`     | The agent's own data directory (where this `graph.yaml` lives) |
+| `LLM_AGENT_DATA_DIR`            | The agent's own data directory (where this `graph.yaml` lives) |
-| `LLM_AGENT_VAR_<NAME>`   | One per declared `variables:` entry; uppercased name           |
+| `LLM_AGENT_VAR_<NAME>`          | One per declared `variables:` entry; uppercased name           |
-| `PATH`                   | Coyote's functions bin dir prepended to the inherited `PATH`     |
+| `PATH`                          | Coyote's functions bin dir prepended to the inherited `PATH`   |
-| `CLICOLOR_FORCE`, `FORCE_COLOR` | Both set to `1` so child tools emit ANSI colors         |
+| `CLICOLOR_FORCE`, `FORCE_COLOR` | Both set to `1` so child tools emit ANSI colors                |
 
 The script's **working directory** is the coyote invocation directory (where
 the user ran `coyote -a <agent> ...`), not the agent directory. This matches
@@ -301,6 +301,15 @@ print(json.dumps({"_next": next_node, "trimmed_codes": codes}))
 node routes to `fallback` (if set) or to `next` (if set). Without either,
 the graph errors.
 
+**Do not pause for user input from inside a script node.** 
+The script process has no TTY and no I/O channel back to the REPL; any interactive prompt
+(`read`, `input()`, password prompts, blocking waits for keypresses, etc.)
+will hang forever and permanently stall the graph. The only supported ways
+to ask the user something from a graph are the [`input`](#input) and
+[`approval`](#approval) node types. The same restriction applies to custom
+agent tools invoked by [`llm`](#llm) nodes. See [Custom Tools](Custom-Tools) for
+more information on custom tools.
+
 ---
 
 ## approval
@@ -1436,6 +1445,13 @@ A short, honest list of things that bite people:
   so a fan-out LLM with `fallback:` matching one of its `next:` targets
   works correctly. The fallback path routes only to the fallback, not
   all Many targets.
+- **Script nodes and custom agent tools cannot pause for user input**.
+  They run as subprocesses with no TTY and no I/O channel back to the
+  REPL; any interactive prompt (`read`, `input()`, password prompts,
+  etc.) will hang forever and permanently stall execution. Use
+  [`input`](#input) and [`approval`](#approval) nodes; they are the
+  only supported pause-for-user points in a graph. The same restriction
+  applies to custom tools invoked from `llm` nodes.
 
 ---