hive.terminal-tools-pty-sessions

1# Persistent PTY sessions
2 
3PTY sessions are how you talk to interactive programs — programs that detect a terminal (`isatty()`) and behave differently when they don't see one. Use a session when:
4 
5- You need state to persist across calls (`cd`, env vars, sourced scripts)
6- You're driving a REPL (`python -i`, `mysql`, `psql`, `node`, `irb`)
7- A program demands an interactive prompt (`sudo`, `ssh`, `npm login`, `gh auth login`)
8 
9For everything else, `terminal_exec` is simpler. Sessions cost more (per-session bash process, ring buffer, idle-reaping bookkeeping) and have a hard cap (`TERMINAL_TOOLS_MAX_PTY`, default 8).
10 
11## Why PTY (and not subprocess pipes)
12 
13Subprocess pipes break on every interactive program. The moment a program calls `isatty()` and sees False, it disables prompts, color, line-editing, password masking, progress bars — sometimes refuses to start. PTY makes us look like a real terminal so these programs work the same as in your shell.
14 
15The cost: PTY output includes terminal escape codes (cursor moves, color codes). The session captures them as-is; if you need clean text, strip ANSI escapes in your processing layer.
16 
17## Bash on macOS — by deliberate policy
18 
19`terminal_pty_open` always invokes `/bin/bash`, regardless of the user's `$SHELL`. macOS users: yes, even when zsh is your interactive default. This is the **terminal-tools-foundations** policy applied to PTYs.
20 
21Reasons:
22…