02 / iTerm2 routing suite / macOS

A send receipt is not delivery evidence.

A composed suite of iTerm2 scripts that discovers a live target, refuses unsafe shells, sends without stealing focus, and verifies what appeared in recent conversation history.

Trace a delivery Inspect the protocol

comms / delivery trace simulation / no machine access

background send pipelineselected / live agent

cookie-authenticated iTerm2 API

01
discoverenumerate live sessions
02
targetexact → substring → variable
03
guardinspect foreground process
04a
type payloadasync_send_text(message)
04b
submitasync_send_text(return)
05
verifyinput box + recent history

$route.ready / choose a scenarioidle

00.000pipeline awaiting runready

delivery protocol

Discover, guard, send, then prove.

comms is a composed script suite, not one opaque sender. Each boundary has a distinct answer and a distinct failure mode.

Discover live state

get-iterm-windows.py enumerates the live iTerm2 application. Cookie authentication is required; cached windows are not substituted for a failed live read.

Resolve the target

Matching proceeds from exact session name, to name substring, to the session variable. No match remains a named failure, not a default route.

Refuse executable surfaces

A bare or unreadable shell is refused because message text would execute as a command. The safe default is no delivery.

Verify two-sided state

The input box must no longer contain the payload, and recent history must contain the prefix, its tail, a queued marker, or a collapsed-paste receipt.

receipt versus evidence

The API returning is only the middle of the story.

Typing and submission are intentionally separate calls. The verifier then reads the rendered surface rather than trusting the sender.

call 01

Type the payload

The first async_send_text places the complete wrapped message into the target input.

call 02

Submit Return

After a short render delay, a separate async_send_text submits the carriage return. One successful call cannot masquerade as both operations.

exit 0

History proves delivery

A recent history fingerprint, queued-message marker, or confirmed collapsed paste supports a verified result.

exit 3

Missing evidence stays ambiguous

An empty input with no matching history can mean a silent failure or scrolled evidence. The result remains uncertain instead of being promoted to success.

composed surface

Small scripts. Explicit seams.

The suite can be inspected, replaced, and tested one responsibility at a time.

iTerm2 comms scripts and their responsibilities
Script	Responsibility	Boundary
`get-iterm-windows.py`	Enumerate live windows and sessions	Live API read only
`read-claude-session.py`	Read visible session contents	No send authority
`detect_claude_state.py`	Share prompt and separator markers	Imported detection vocabulary
`parse-question.py`	Detect prompts and options	Reports the parse
`answer-question.py`	Operate a prompt already on screen	Refuses weak multi-select reads
`send-message.py`	Address, guard, submit, and verify	Explicit exit status

0submitted / verified

Recent history or a recognized queued state supports delivery.

2not submitted

The payload remains in the target input box.

3ambiguous

Anchors or positive history evidence are missing.

4no target

No matching live window or session was found.

6shell refused

The foreground is a shell or cannot be read safely.

sender surface

python3 send-message.py <target> <message> --from <role>

A sender header, UTC timestamp, and reply instruction are added when --from is present. Bare sends remain available for human-authored dashboard messages and slash commands.

bring the route

Make the handoff observable.

Bring a coordination path that currently depends on focus changes, clipboard state, or hope after a send call returns.

Propose a comms route Inspect doff