@xynogen/pix-ssh 0.2.2 → 0.2.3

package/README.md

@@ -1,12 +1,15 @@
 # pix-ssh
 
-Pi tool — `ssh_run`: run a shell command on a remote host over SSH, optionally as remote root.
+Pi tool — `ssh_run`: run a command through a remote host's configured SSH shell, optionally through POSIX `sudo`.
+
+> [!IMPORTANT]
+> Basic Windows `cmd`, Windows PowerShell, and `pwsh` commands may work through the configured SSH shell, but support is best-effort. Shell selection, complex quoting, PowerShell error/stream/encoding semantics, interactive prompts, and Windows administrator/UAC elevation are not covered. The agent should back away when correctness depends on those limits. `sudo: true` supports POSIX `sudo` only.
 
 ## What it does
 
-Registers the `ssh_run` tool, which executes a command on a remote machine behind a permission dialog (the shared overlay from `@xynogen/pix-pretty`, the same one pix-sudo uses). Every command requires explicit per-call Allow/Deny approval in the UI, with a 60-second auto-deny timeout — that approval step is never skipped. Output is truncated to 50 KB / 2000 lines. In non-interactive (RPC/JSON) mode the tool is blocked immediately.
+Registers the `ssh_run` tool, which executes a command through the configured SSH shell on a remote machine behind a permission dialog (the shared overlay from `@xynogen/pix-pretty`, the same one pix-sudo uses). Initial and privileged calls require Allow/Deny approval in the UI, with a 60-second auto-deny timeout. Non-privileged calls may be auto-approved during the 15-minute per-host approval window or in YOLO mode when no password is missing; each host-window auto-approval emits a notification. Output is truncated to 50 KB / 2000 lines. In non-interactive (RPC/JSON) mode the tool is blocked immediately.
 
-**Parameters:** `host` as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`), `command`, optional `sudo` (run as root on the remote), optional `reason`.
+**Parameters:** `host` as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`), `command`, optional `sudo` (run through POSIX `sudo` as root), optional `reason`.
 
 ### Authentication
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-ssh",
-	"version": "0.2.2",
+	"version": "0.2.3",
 	"description": "Pi tool — ssh_run: run remote commands over SSH with password/key auth and remote sudo",
 	"type": "module",
 	"main": "src/index.ts",

package/src/index.ts

@@ -217,17 +217,22 @@ export default function (pi: ExtensionAPI): void {
 		name: "ssh_run",
 		label: "Run over SSH",
 		description:
-			"Run a shell command on a remote host over SSH, optionally as root (remote sudo). " +
-			"Handles the connection and any password entry through a confirmation dialog — " +
-			"the command is NEVER executed without explicit user approval. " +
+			"Run a command through the remote host's configured SSH shell, optionally through POSIX sudo. " +
+			"Basic cmd/PowerShell/pwsh commands may work, but Windows shells are best-effort: shell selection, " +
+			"quoting, PowerShell error/stream/encoding semantics, interactive prompts, and Windows " +
+			"administrator/UAC elevation are not supported. Back away and tell the user when correctness " +
+			"depends on one of those limits. Handles connection and password entry through a permission dialog. " +
+			"A configured approval window or YOLO mode may auto-approve non-privileged commands when no password is missing. " +
 			"SSH auth tries key/agent first, then prompts for a login password if needed. " +
 			"Set `sudo: true` to run the command as root on the remote machine (prompts for the " +
 			"remote sudo password). Always provide a clear `reason`.",
-		promptSnippet: "Run a command on a remote host over SSH (optionally as remote root)",
+		promptSnippet: "Run a remote SSH command (Windows shells best-effort; POSIX sudo only)",
 		promptGuidelines: [
-			"Use ssh_run to execute commands on a remote machine over SSH. Provide `host` as " +
-				"`[user@]host[:port]`. Set `sudo: true` only when the remote command needs root. " +
-				"Always set `reason` to a short plain-English sentence explaining the intent.",
+			"ssh_run sends commands to the remote host's configured SSH shell. Basic cmd, PowerShell, or " +
+				"pwsh commands may work, but treat Windows shells as best-effort. Back away and tell the user " +
+				"when correctness depends on explicit shell selection, complex quoting, PowerShell error/stream/encoding " +
+				"semantics, interactive prompts, or Windows administrator/UAC elevation. `sudo` covers POSIX sudo " +
+				"only. Provide `host` as `[user@]host[:port]` and always explain the intent in `reason`.",
 		],
 
 		renderShell: "self",
@@ -237,7 +242,7 @@ export default function (pi: ExtensionAPI): void {
 				description: "Remote target as `[user@]host[:port]` (e.g. `deploy@10.0.0.5:2222`).",
 			}),
 			command: Type.String({
-				description: "Shell command to run on the remote host (passed to remote `sh -c`).",
+				description: "Command sent to the remote host's configured SSH shell.",
 			}),
 			sudo: Type.Optional(
 				Type.Boolean({