hive.terminal-tools-pty-sessions

Persistent PTY sessions

PTY 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:

• You need state to persist across calls (cd, env vars, sourced scripts)
• You're driving a REPL (python -i, mysql, psql, node, irb)
• A program demands an interactive prompt (sudo, ssh, npm login, gh auth login)

For 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).

Why PTY (and not subprocess pipes)

Subprocess 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.

The 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.

Bash on macOS — by deliberate policy

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.

Reasons:

• zsh has command/builtin classes (zmodload, =cmd expansion, zpty, ztcp) that bypass bash-shaped security checks
• One shell behavior across platforms eliminates "works on Linux, breaks on macOS" surprises
• Bash is universal: any shell you've used will accept the bash subset

The bash invocation uses --norc --noprofile so user dotfiles don't leak in. PS1 is set to a unique sentinel for prompt detection. PS2 is empty. PROMPT_COMMAND is empty.

Three modes of terminal_pty_run

1. Default: send command, wait for prompt sentinel

terminal_pty_run(session_id, command="ls -la")
  → { output, prompt_after: True, ... }