# PROP: PTY Passthrough Layer for Native CLI Transparency

## Source
- **URL**: https://github.com/turtlekazu/crai (pattern reference), https://github.com/pexpect/pexpect (implementation library)
- **Author**: crai by turtlekazu; pexpect by Noah Spurrier / Thomas Kluyver
- **Date**: 2026 (crai), mature (pexpect)

## Summary
Build a transparent PTY bridge that spawns Claude Code CLI, Codex CLI, or any future AI CLI tool inside a pseudo-terminal, bridging stdin/stdout with zero transformation. Users get the exact native experience (colors, spinners, keybindings, interactive prompts) while iEvo can observe and inject events. Inspired by crai's PTY transparency pattern and CLIProxyAPI's multi-CLI support.

## Relevance to iEvo
This is the foundational layer for the "native CLI passthrough" vision. Currently iEvo runs Claude Code via `subprocess` with piped stdio, which loses interactive features. A PTY bridge preserves 100% of the native CLI experience while allowing iEvo to:
- Monitor tool calls and agent activity
- Inject context (evolution overlays, memory) via Claude Code's hook system
- Track session metrics (tokens, duration, tool calls)
- Switch between CLI providers transparently

## Proposed Change
Create `src/ievo/core/pty_bridge.py` with:

1. **`PtyBridge` class**: Spawns a CLI command inside a PTY using Python's `pty` module or `pexpect.spawn()`. Bridges raw stdin/stdout bidirectionally. All output passes through unmodified.

2. **Event detection layer**: Optional output monitor that looks for structured patterns (JSON events from Claude Code hooks, Codex output markers) without modifying the stream. Fires callbacks on detected events.

3. **CLI launcher registry**: Maps provider names to CLI commands:
   - `claude` -> `claude -p` (or `claude --agent`)
   - `codex` -> `codex` (with appropriate flags)
   - `ollama` -> `ollama run <model>` (interactive mode)

4. **Graceful lifecycle**: Handle SIGINT/SIGTERM forwarding to child process. Clean shutdown. Resume support via session ID.

Key design constraint: the bridge is transparent by default. No transformation, no parsing, no buffering. Event detection is opt-in and read-only.

## Affected Components
- New: `src/ievo/core/pty_bridge.py`
- Modified: `src/ievo/core/docker.py` (use PtyBridge for container exec)
- Modified: `src/ievo/tui/app.py` (terminal widget shows PTY output)
- New dependency: `pexpect` (or use stdlib `pty` + `select` for minimal deps)

## Scores
- Applicability: 5/5
- Effort: low-medium (~200 lines core, well-understood PTY patterns)
- Impact: UX (preserves native experience), reliability (no stdio buffering issues)
