Add atomic run/wait/capture tool with exit status #73

Problem

The dominant agent workflow is: run a command in a pane, wait for completion, capture output, and know whether it succeeded. Today this requires multi-call composition and does not preserve exit status in the prompt recipe.

Open issue #49 covers batching send_keys. Open issue #61 covers observation-first architecture. Neither provides a single typed run/wait/capture/status tool.

Minimal target behavior

Add one tool for commands the agent authors:

run_command(
  pane_id,
  command,
  timeout=30,
  capture_lines=200,
  socket_name=None
) -> {
  pane_id,
  command,
  exit_status,
  timed_out,
  output,
  truncated
}

The tool should:

• send a shell payload into the target pane,
• signal a generated tmux wait channel on completion,
• preserve $? without exiting the interactive shell,
• wait via tmux wait-for,
• capture recent output,
• return a typed result.

Upstream references

• tmux wait-for is the right zero-poll synchronization primitive: https://github.com/tmux/tmux/blob/3.6a/cmd-wait-for.c
• CPython asyncio.to_thread delegates work to an executor: https://github.com/python/cpython/blob/v3.15.0b1/Lib/asyncio/threads.py#L12-L25
• CPython subprocess.run(timeout=...) kills the managed child on timeout: https://github.com/python/cpython/blob/v3.15.0b1/Lib/subprocess.py#L627-L687

Minimal fix

Implement only the POSIX-shell path first. Do not add shell autodetection or fish/zsh-specific status variants in this issue.

Use a generated channel and a generated tmux pane option or temporary marker to store status.

Minimal local recreation

Manual composition today:

$ tmux send-keys -t %1 'false; status=$?; tmux set-option -p @libtmux_mcp_status_test "$status"; tmux wait-for -S libtmux_mcp_done_test' Enter
$ tmux wait-for libtmux_mcp_done_test
$ tmux show-option -p @libtmux_mcp_status_test

Expected: status is 1.

Acceptance criteria

• Tool returns exit_status=0 for true.
• Tool returns nonzero status for false.
• Tool returns timed_out=True and does not hang indefinitely for sleep 60 with a short timeout.
• Tool captures bounded recent output.
• Tool does not exit or kill the interactive shell.
• Docs state that this tool is for commands authored by the agent.