Skip to content

Expose the shell's prompt/command state from OSC 133 - #192

Merged
tomlm merged 2 commits into
tomlm:mainfrom
confetty-sh:stack/xterm-net-control-claude
Nov 9, 2026
Merged

tomlm merged 2 commits into
tomlm:mainfrom
confetty-sh:stack/xterm-net-control-claude

Conversation

@JohnCampionJr

@JohnCampionJr JohnCampionJr commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Why

A host that wants to confirm before closing a terminal, but only when closing would kill something, needs to ask whether a command is running. That's Ghostty's prompt-aware confirm-close-surface: ask while a command runs, close quietly at an idle prompt. OSC 133 already carries the answer, and ShellIntegrationState exposes the raw last mark. But a host still has to map four marks plus null onto "running or not", and it has no change event, so it can't react without polling.

API (additive)

  • XTerm.Common.ShellState enum: Unknown, Prompt, Input, Running.
  • Terminal.ShellState, read-only.
  • Terminal.ShellStateChanged, with TerminalEvents.ShellStateChangedEventArgs(OldState, NewState, ExitCode). It fires only when the value actually changes. ExitCode is the code from the 133;D that ended a command, and null otherwise.
  • Terminal.ResetShellState(): back to Unknown, leaving the screen, the scrollback and the anchored marks alone. It's for a host that connects the terminal to a different process; without it, a new shell that never sends a mark would be described forever by the old shell's last one. RIS uses it too.

The transitions are documented on the enum:

  • A → Prompt, B → Input, C → Running.
  • D → Prompt. The command is over and the shell has the terminal back. It isn't Unknown, because the shell just said where it is.
  • RIS → Unknown. DECSTR leaves it alone.

Each mark sets the state outright, so the latest mark always wins:

  • A lost D (a crashed shell, a killed command) is repaired by the next prompt's A.
  • Out-of-order marks and nested shells follow whichever shell spoke last.
  • The alternate screen doesn't affect it.

Compatibility

Purely additive. ShellIntegrationState, LastCommandExitCode and ShellIntegrationMarkReceived are unchanged. ShellState is updated before the existing mark event is raised, so a mark handler that reads it sees the new value. The OSC 133 handler is not on the hot path.

Tests

ShellIntegrationTests gains 17 cases:

  • each mark, and a full A/B/C/D cycle with its event sequence;
  • the exit code, and a bare D giving null;
  • repeated marks raising nothing;
  • RIS while running (then the D that follows), RIS with no state, and soft reset;
  • ResetShellState forgetting the state but not the screen;
  • a missing D recovered by A, out-of-order marks, and nested shells;
  • the alternate screen, unknown marks, and state ordering against the mark event.

All 50 tests in the class pass. Mutation runs killed all 10 mutants:

  • dropping the RIS reset, or RIS skipping ResetShellState;
  • a no-op ResetShellState;
  • removing the dedupe;
  • D → Unknown;
  • B → Prompt;
  • refusing A while Running;
  • swapping old and new;
  • dropping the exit code;
  • raising the mark event before updating the state.

The README's events section documents the API.

🤖 Generated with Claude Code

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants