mcp(docs[audit]): Clarify env redaction

why: Describe both accepted respawn environment representations and
their distinct audit summaries.

what:
- Explain per-key redaction for mapping input
- Explain scalar redaction for JSON object strings

Author: tony

docs/topics/safety.md

@@ -111,7 +111,7 @@ Mitigations:
 
 - `pane_id` is required (no fallback to "first pane in session/window"). Agents that pass only `session_name` get an {exc}`~libtmux_mcp._utils.ExpectedToolError` 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 optional `environment` argument accepts either a mapping of string keys and values or a JSON object string, then maps each item to one tmux `-e KEY=VALUE` flag. For a mapping, the audit log keeps each *key* visible and replaces each *value* with a `{len, sha256_prefix}` digest. A JSON string is redacted as one scalar digest, so its keys are not retained in the audit record. 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.
 
 ### Raw pane input

src/libtmux_mcp/middleware.py

@@ -440,11 +440,10 @@ async def on_call_tool(
 #: secrets, or arbitrary large strings.
 #: Matched by exact name, case-sensitive, to mirror the tool signatures.
 #:
-#: ``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.
+#: ``environment`` accepts a mapping or a JSON object string. The redaction
+#: logic in :func:`_summarize_args` digests each mapping *value* while leaving
+#: its *keys* (env var names like ``DATABASE_URL``) visible. A JSON string is
+#: instead redacted as one scalar digest, so its keys are not retained.
 #:
 #: Note on ``shell`` and ``environment`` redaction: this redacts the MCP
 #: audit log only. ``respawn_pane(shell="env SECRET=... bash")`` and

src/libtmux_mcp/tools/pane_tools/lifecycle.py

@@ -124,11 +124,13 @@ def respawn_pane(
         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
+        supplied in a mapping 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.
+        A JSON object string is redacted as one scalar digest, so its
+        keys are not retained in the audit record. 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.