mcp(feat[pane_tools]): expose respawn-pane environment override

Closes the parity gap with libtmux's ``Pane.respawn(environment=)``
on the ``tmux-parity`` branch. The new ``environment: dict[str, str]``
parameter on ``respawn_pane`` maps to one ``-e KEY=VALUE`` flag per
entry (single-arg ``-e<KEY>=<VAL>`` form, mirroring upstream's
emitter — tmux's ``cmd-respawn-pane.c`` accepts both joined and split
forms but upstream uses joined). The stopgap comment is updated to
include ``-e`` so the eventual swap to ``pane.respawn(environment=)``
is a single internal change.

Audit-log redaction is extended to recognise dict-shaped sensitive
args. Each ``environment`` *value* is replaced by a ``{len,
sha256_prefix}`` digest while keys remain visible (env var names
like ``DATABASE_URL`` are operator-debug-useful; values are the
secret). The same OS-process-table caveat as ``shell`` applies and
is documented in ``docs/topics/safety.md`` under the ``respawn_pane``
subsection — the audit log redacts, but ``ps`` may still observe the
flag string briefly before the spawned process inherits the env.

Tests cover the new redaction shape (`tests/test_middleware.py`) and
the runtime propagation path (`tests/test_pane_tools.py` —
``printenv`` under ``remain-on-exit`` so the assertion runs against
captured pane content, with ``capture-pane -S -50`` to read enough
scrollback even on a small pane).

Author: tony

CHANGES

@@ -6,6 +6,22 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### Features
+
+- {tooliconl}`respawn-pane` gains an ``environment`` parameter
+  (``dict[str, str]``) that maps to tmux's ``respawn-pane -e
+  KEY=VALUE`` flag (one ``-e`` per entry, single-arg ``-e<KEY>=<VAL>``
+  form to mirror the upstream emitter). Closes the parity gap with
+  ``Pane.respawn(environment=)`` on libtmux's ``tmux-parity`` branch.
+  The audit-log redaction policy is extended to recognise dict-shaped
+  sensitive args: each value is replaced by a ``{len, sha256_prefix}``
+  digest while keys (env var names like ``DATABASE_URL``) remain
+  visible — keys are operator-debug-useful, values are the secret.
+  Note: like ``shell``, env var values may briefly appear in the OS
+  process table before the spawned shell inherits them; do not pass
+  long-lived secrets when other tenants on the host could observe
+  ``ps``.
+
 ### Tests
 
 - New ``test_registered_tools_accept_socket_name`` introspection test

docs/tools/pane/respawn-pane.md

@@ -8,7 +8,8 @@ process, bad terminal mode) and you need a clean restart *without*
 destroying the `pane_id` references other tools or callers may still
 be holding. With `kill=True` (the default) tmux kills the current
 process first; optional `shell` relaunches with a different command;
-optional `start_directory` sets its cwd.
+optional `start_directory` sets its cwd; optional `environment` adds
+per-process env vars (one `-e KEY=VALUE` flag per entry).
 
 **Avoid when** the pane genuinely needs to go away — use
 {tooliconl}`kill-pane` instead. Also avoid when you want to change
@@ -48,6 +49,24 @@ time).
 }
 ```
 
+**Example — relaunch with extra environment variables:**
+
+```json
+{
+  "tool": "respawn_pane",
+  "arguments": {
+    "pane_id": "%5",
+    "shell": "pytest -x",
+    "environment": {
+      "PYTHONPATH": "/home/user/project/src",
+      "DATABASE_URL": "postgres://localhost/test"
+    }
+  }
+}
+```
+
+The audit log redacts each `environment` *value* via `{len, sha256_prefix}` digests but keeps the keys visible (env var names like `DATABASE_URL` are operator-debug-useful, while their values are the secret). Note that values may still appear briefly in the OS process table while tmux spawns the new process — see {ref}`safety` for details.
+
 Response (PaneInfo):
 
 ```json

docs/topics/safety.md

@@ -104,6 +104,7 @@ Mitigations:
 
 - `pane_id` is required (no fallback to "first pane in session/window"). Agents that pass only `session_name` get a `ToolError` instead of an unintended kill — resolve via {tool}`list-panes` first.
 - Any `shell` argument is briefly visible in the OS process table and tmux's `pane_current_command` metadata before the spawned shell takes over; the audit log redacts `shell` payloads (see below), but do not pass credentials directly even with redaction.
+- The optional `environment` argument (`dict[str, str]`) maps to one tmux `-e KEY=VALUE` flag per item. The audit log redacts each *value* via a `{len, sha256_prefix}` digest while keeping the *keys* visible — env var names like `DATABASE_URL` are usually operator-debug-useful, but their values are the secret. The same OS-process-table caveat as `shell` applies: `respawn-pane -e DB_PASSWORD=...` may briefly appear in `ps` output before the spawned process inherits the env.
 - The same self-pane guard that protects the destructive kill commands also refuses to respawn the pane running the MCP server.
 
 ### `send_keys` / `paste_text`
@@ -118,7 +119,7 @@ Every tool call emits one `INFO` record on the `libtmux_mcp.audit` logger carryi
 - `outcome` — `ok` or `error`, with `error_type` on failure
 - `duration_ms`
 - `client_id` / `request_id` — from the fastmcp context when available
-- `args` — a summary of arguments. Sensitive keys (`keys`, `text`, `value`, `content`, `shell`) are replaced by `{len, sha256_prefix}`; non-sensitive strings over 200 characters are truncated.
+- `args` — a summary of arguments. Sensitive scalar keys (`keys`, `text`, `value`, `content`, `shell`) are replaced by `{len, sha256_prefix}`; the dict-shaped sensitive key `environment` keeps its keys but digests each value individually. Non-sensitive strings over 200 characters are truncated.
 
 Route this logger to a dedicated sink if you want a durable audit trail; it is deliberately namespaced separately from the main `libtmux_mcp` logger.
 

src/libtmux_mcp/middleware.py

@@ -100,16 +100,23 @@ async def on_call_tool(
 
 #: Argument names that carry user-supplied payloads we never want in logs.
 #: ``keys`` (send_keys), ``text`` (paste_text), ``value`` (set_environment),
-#: ``content`` (load_buffer), and ``shell`` (respawn_pane) can contain
-#: commands, secrets, or arbitrary large strings. Matched by exact name,
-#: case-sensitive, to mirror the tool signatures.
+#: ``content`` (load_buffer), ``shell`` (respawn_pane), and ``environment``
+#: (respawn_pane) can contain commands, secrets, or arbitrary large strings.
+#: Matched by exact name, case-sensitive, to mirror the tool signatures.
 #:
-#: Note on ``shell`` redaction: this redacts the MCP audit log only.
-#: ``respawn_pane(shell="env SECRET=... bash")`` may briefly expose the
-#: argument via the OS process table and tmux's ``pane_current_command``
-#: metadata until the spawned shell takes over — see ``docs/topics/safety.md``.
+#: ``environment`` is dict-shaped (``dict[str, str]``); the redaction logic
+#: in :func:`_summarize_args` recognises this and digests each *value* while
+#: leaving the *keys* (env var names like ``DATABASE_URL``) visible — env
+#: var names are operator-debug-useful, but their values are the secret.
+#: All other entries are scalar strings; mixing the two is intentional.
+#:
+#: Note on ``shell`` and ``environment`` redaction: this redacts the MCP
+#: audit log only. ``respawn_pane(shell="env SECRET=... bash")`` and
+#: ``environment={"AWS_SECRET_KEY": "..."}`` may briefly expose the values
+#: via the OS process table and tmux's ``pane_current_command`` metadata
+#: until the spawned shell takes over — see ``docs/topics/safety.md``.
 _SENSITIVE_ARG_NAMES: frozenset[str] = frozenset(
-    {"keys", "text", "value", "content", "shell"}
+    {"keys", "text", "value", "content", "shell", "environment"}
 )
 
 #: String arguments longer than this get truncated in the log summary to
@@ -143,6 +150,10 @@ def _summarize_args(args: dict[str, t.Any]) -> dict[str, t.Any]:
 
     Sensitive keys get replaced by a digest; over-long strings get
     truncated with a marker; everything else passes through as-is.
+    Sensitive values that are dict-shaped (e.g. ``environment`` on
+    ``respawn_pane``) have each *value* digested while keys remain
+    visible — env-var-name-like keys are operator-debug-useful and
+    rarely sensitive, while their values usually are.
 
     Examples
     --------
@@ -155,11 +166,21 @@ def _summarize_args(args: dict[str, t.Any]) -> dict[str, t.Any]:
 
     >>> _summarize_args({"keys": "rm -rf /"})["keys"]["len"]
     8
+
+    Sensitive dict-shaped payloads keep their keys but digest values:
+
+    >>> redacted = _summarize_args({"environment": {"FOO": "bar"}})
+    >>> redacted["environment"]["FOO"]["len"]
+    3
+    >>> "bar" in str(redacted)
+    False
     """
     summary: dict[str, t.Any] = {}
     for key, value in args.items():
-        if isinstance(value, str) and key in _SENSITIVE_ARG_NAMES:
+        if key in _SENSITIVE_ARG_NAMES and isinstance(value, str):
             summary[key] = _redact_digest(value)
+        elif key in _SENSITIVE_ARG_NAMES and isinstance(value, dict):
+            summary[key] = {k: _redact_digest(str(v)) for k, v in value.items()}
         elif isinstance(value, str) and len(value) > _MAX_LOGGED_STR_LEN:
             summary[key] = value[:_MAX_LOGGED_STR_LEN] + "...<truncated>"
         else:

src/libtmux_mcp/tools/pane_tools/lifecycle.py

@@ -67,6 +67,7 @@ def respawn_pane(
     kill: bool = True,
     shell: str | None = None,
     start_directory: str | None = None,
+    environment: dict[str, str] | None = None,
     socket_name: str | None = None,
 ) -> PaneInfo:
     """Restart a pane's process in place, preserving pane_id and layout.
@@ -79,7 +80,9 @@ def respawn_pane(
     With ``kill=True`` (the default), tmux kills the existing process
     before respawning. Optional ``shell`` replaces the command tmux
     relaunches; ``start_directory`` sets the working directory for
-    the new process.
+    the new process; ``environment`` sets per-process environment
+    variables for the relaunched command (one ``-e KEY=VALUE`` flag
+    per entry).
 
     ``pane_id`` is required — no fallback to ``_resolve_pane``'s
     "first pane in session/window" behaviour. Default ``kill=True``
@@ -118,6 +121,16 @@ def respawn_pane(
     start_directory : str, optional
         Working directory for the relaunched command (maps to
         ``respawn-pane -c``).
+    environment : dict[str, str], optional
+        Environment variables to set for the relaunched process. Each
+        item becomes one ``-e KEY=VALUE`` flag (tmux's
+        ``cmd-respawn-pane.c`` supports the flag repeatedly). Values
+        are redacted in the audit log on a per-key basis — keys like
+        ``DATABASE_URL`` remain visible but their values are replaced
+        by ``{len, sha256_prefix}`` digests. Note that the values may
+        still appear briefly in the OS process table while tmux spawns
+        the new process; do not pass long-lived secrets here when a
+        host-resident agent or other tenant could observe ``ps``.
     socket_name : str, optional
         tmux socket name.
 
@@ -155,16 +168,21 @@ def respawn_pane(
         raise ToolError(msg)
     # Stopgap: ``libtmux>=0.55.1`` has no ``Pane.respawn()`` yet — the
     # wrapper exists on the upstream ``tmux-parity`` branch (see
-    # ``libtmux/pane.py:respawn``) and mirrors this argv shape (``-k``,
-    # ``-c <dir>``, optional trailing shell). When the release line picks
-    # it up, swap ``pane.cmd("respawn-pane", *argv)`` for ``pane.respawn(
-    # kill=kill, start_directory=start_directory, shell=shell)`` and drop
+    # ``libtmux/pane.py:respawn``) and mirrors this argv shape: ``-k``,
+    # ``-c <dir>``, repeated ``-e<KEY>=<VAL>`` (single-arg form, NOT
+    # split ``-e KEY=VAL`` — tmux's args parser accepts both but
+    # upstream emits the joined form), then optional trailing shell.
+    # When the release line picks it up, swap ``pane.cmd("respawn-pane",
+    # *argv)`` for ``pane.respawn(kill=kill, start_directory=
+    # start_directory, environment=environment, shell=shell)`` and drop
     # the stderr branch — ``Pane.respawn`` raises ``LibTmuxException``.
     argv: list[str] = []
     if kill:
         argv.append("-k")
     if start_directory is not None:
         argv.extend(["-c", start_directory])
+    if environment:
+        argv.extend(f"-e{k}={v}" for k, v in environment.items())
     if shell is not None:
         argv.append(shell)
     result = pane.cmd("respawn-pane", *argv)

tests/test_middleware.py

@@ -167,6 +167,38 @@ def test_summarize_args_redacts_sensitive_keys() -> None:
     assert summary["bracket"] is True
 
 
+def test_summarize_args_redacts_sensitive_dict_values() -> None:
+    """Dict-shaped sensitive args keep keys but digest values per-entry.
+
+    ``environment`` on ``respawn_pane`` is a ``dict[str, str]``. The
+    values typically carry secrets (DB passwords, API keys), but the
+    keys (``DATABASE_URL``, ``AWS_SECRET_KEY``) are operator-useful for
+    debugging which env var was set. The redaction policy preserves
+    keys and digests values.
+    """
+    args: dict[str, t.Any] = {
+        "environment": {
+            "DATABASE_URL": "postgres://user:hunter2@db/app",
+            "AWS_SECRET_KEY": "AKIAIOSFODNN7EXAMPLE",
+        },
+        "pane_id": "%1",
+    }
+    summary = _summarize_args(args)
+    assert isinstance(summary["environment"], dict)
+    assert set(summary["environment"].keys()) == {"DATABASE_URL", "AWS_SECRET_KEY"}
+    for key in ("DATABASE_URL", "AWS_SECRET_KEY"):
+        digest = summary["environment"][key]
+        assert isinstance(digest, dict)
+        assert "len" in digest
+        assert "sha256_prefix" in digest
+    # No value bytes leak into the rendered summary.
+    rendered = str(summary)
+    assert "hunter2" not in rendered
+    assert "AKIAIOSFODNN7EXAMPLE" not in rendered
+    # Non-sensitive args still pass through.
+    assert summary["pane_id"] == "%1"
+
+
 def test_summarize_args_truncates_long_non_sensitive_strings() -> None:
     """Non-sensitive strings over the cap get truncated with a marker."""
     args = {"output_path": "x" * 500}

tests/test_pane_tools.py

@@ -405,6 +405,51 @@ def test_respawn_pane_kill_false_on_live_pane_raises(
     new_pane.kill()
 
 
+def test_respawn_pane_with_environment(
+    mcp_server: Server, mcp_session: Session
+) -> None:
+    """``environment`` propagates through to the relaunched process.
+
+    tmux's ``respawn-pane -e KEY=VALUE`` sets per-process env vars on
+    the spawned command (``cmd-respawn-pane.c`` accepts the flag
+    repeatedly). Verify by relaunching with ``sh -c 'env'`` under
+    ``remain-on-exit`` so we can capture the env output after the
+    process exits without tmux deleting the pane out from under us.
+    """
+    window = mcp_session.active_window
+    window.cmd("set-option", "-w", "remain-on-exit", "on")
+    new_pane = window.split(shell="sleep 3600")
+    assert new_pane.pane_id is not None
+
+    # Use ``printenv`` over ``env`` so the output fits the visible pane
+    # (default capture-pane reads only the visible screen, not history).
+    # Wrap the values in markers so we don't false-match on similarly
+    # named host env vars that might already be set.
+    result = respawn_pane(
+        pane_id=new_pane.pane_id,
+        shell="sh -c 'printenv LIBTMUX_TEST_FOO LIBTMUX_TEST_BAZ'",
+        environment={"LIBTMUX_TEST_FOO": "bar", "LIBTMUX_TEST_BAZ": "qux"},
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.pane_id == new_pane.pane_id
+
+    def _pane_dead() -> bool:
+        out = new_pane.cmd("display-message", "-p", "#{pane_dead}").stdout
+        return bool(out) and out[0].strip() == "1"
+
+    retry_until(_pane_dead, seconds=5, raises=True)
+
+    # ``-S -50`` reads the last 50 lines of scrollback so we don't lose
+    # the first ``printenv`` line off the top of the visible screen.
+    captured = new_pane.cmd("capture-pane", "-p", "-S", "-50").stdout
+    rendered = "\n".join(captured)
+    assert "bar" in rendered
+    assert "qux" in rendered
+
+    new_pane.kill()
+    window.cmd("set-option", "-wu", "remain-on-exit")
+
+
 # ---------------------------------------------------------------------------
 # search_panes tests
 # ---------------------------------------------------------------------------