feat(tool): add interactive terminal tool with persistent PTY sessions

Problem

The current bash tool only supports one-shot command execution. The agent cannot interact with long-running processes, send follow-up input, or read incremental output from a running terminal session. This limits the agent's ability to work with REPLs, debuggers, servers, and other interactive CLI tools.

Proposed Solution

Add a new terminal tool with an action parameter that supports persistent PTY sessions:

run (default, backward-compatible): Same as current bash tool behavior
create: Start a persistent PTY session, returns sessionId
send: Write input to an existing session (commands, keystrokes, control sequences like Ctrl+C)
read: Read incremental output since last read using cursor-based replay
close: Terminate a session and clean up resources

Key design decisions:

Sessions stored via InstanceState<Map<PtyID, SessionState>> for per-directory isolation with auto-cleanup on disposal
FIFO eviction at max 20 sessions (oldest evicted first)
PowerShell exit code fix: uses $LASTEXITCODE instead of $? on Windows
Cursor-based output reading: no duplication, aligns with Pty.Service buffer model
Discriminated union Zod schema for type-safe parameter destructuring
Backward compatible: omitting action defaults to "run", producing identical behavior to the current bash tool

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

This appears to be a feature request, but the title does not start with [FEATURE]: as required by the feature request template
The feature request template's pre-flight verification checkboxes are missing (confirming the feature hasn't been suggested before and that status:approved is needed before opening a PR)

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

This issue might be a duplicate of existing issues. Please check:

[FEATURE]: Agent should use integrated terminal (PTY) instead of spawning new shell processes #23449: Nearly identical request — also by you — proposing exposing the integrated PTY as an agent tool instead of spawning new shell processes. This issue is already open and assigned to a developer.
[FEATURE]: Opt-in Host-Shell Execution Mode with Full stdin Passthrough #18659: Feature request for opt-in host-shell execution mode with full stdin passthrough (interactive PTY support)
[FEATURE]: Better active/background terminal and bash management #6375: Feature request for better active/background terminal and bash management

If you believe this was flagged incorrectly, please let a maintainer know.

This issue has been automatically closed because it was not updated to meet our contributing guidelines within the 2-hour window.

Feel free to open a new issue that follows our issue templates.

feat(tool): add interactive terminal tool with persistent PTY sessions

Navigation Menu

Repository navigation

feat(tool): add interactive terminal tool with persistent PTY sessions #23759

Problem

Proposed Solution

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

feat(tool): add interactive terminal tool with persistent PTY sessions #23759

Description

Problem

Proposed Solution

Activity

github-actions commented on Apr 21, 2026

github-actions commented on Apr 22, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions