feat(command-runner): add custom command execution with session whitelist promotion

- Add "Custom Command..." entry at the top of the command menu for all
  target types (host, LXC container, QEMU VM)
- Execute arbitrary non-interactive commands without whitelist validation,
  still applying the configured timeout and output size limit
- Add ExecuteCustomHostCommand, ExecuteCustomContainerCommand, and
  ExecuteCustomVMCommand on Executor (skip validator, same SSH/agent paths)
- Add AddToWhitelist on Executor for session-only in-memory promotion
- After a successful custom run, pressing 'w' on the result screen saves
  the command to the session whitelist and inserts it at index 1 in the
  live list widget immediately — no close/reopen required
- Fix backspace bubbling in parameter and custom command forms: only ESC
  closes the form, leaving backspace available for text editing
- Register "customCommandForm" modal page name in the outer UI plugin

Author: devnullvoid

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **Command Runner: Custom Commands**: The Command Runner plugin now exposes a "Custom Command..." entry at the top of the command menu for all target types (host, LXC container, QEMU VM). Users can type any non-interactive command and execute it directly without it needing to be on the whitelist. After a successful run, pressing `w` on the result screen promotes the command into the session whitelist and inserts it at the top of the command list immediately — no close/reopen required. Commands run without a PTY; `sudo` requiring a password will fail fast with a clear error, as will interactive programs.
+
 - **CLI Subcommands**: `pvetui` can now be used as a non-interactive CLI tool in addition to launching the TUI. Running any subcommand bypasses the TUI entirely, making `pvetui` composable in scripts and AI agent workflows.
   - `pvetui nodes list` — list all cluster nodes with status and resource metrics.
   - `pvetui nodes show <node>` — detailed view of a single node.

internal/plugins/command-runner/executor.go

@@ -294,6 +294,123 @@ func (e *Executor) GetAllowedVMCommands(vm VM) []string {
 	return e.validator.GetAllowedVMCommands(vm)
 }
 
+// AddToWhitelist adds a command to the in-memory whitelist for a target type.
+// This change is session-only and does not persist to the config file.
+func (e *Executor) AddToWhitelist(targetType TargetType, command string) {
+	switch targetType {
+	case TargetHost:
+		e.config.AllowedCommands.Host = append(e.config.AllowedCommands.Host, command)
+	case TargetContainer:
+		e.config.AllowedCommands.Container = append(e.config.AllowedCommands.Container, command)
+	case TargetVM:
+		e.config.AllowedCommands.VM = append(e.config.AllowedCommands.VM, command)
+	}
+	// Refresh the validator so it picks up the new entry.
+	e.validator = NewValidator(e.config)
+}
+
+// ExecuteCustomHostCommand executes an arbitrary command on a host via SSH without
+// whitelist validation. The command must be non-interactive; sudo requiring a password
+// will fail immediately because no PTY is allocated.
+func (e *Executor) ExecuteCustomHostCommand(ctx context.Context, host, command string) ExecutionResult {
+	start := time.Now()
+
+	result := ExecutionResult{Command: command}
+
+	ctx, cancel := context.WithTimeout(ctx, e.config.Timeout)
+	defer cancel()
+
+	output, err := e.sshClient.ExecuteCommand(ctx, host, command)
+	result.Duration = time.Since(start)
+
+	if err != nil {
+		result.Error = fmt.Errorf("execution failed: %w", err)
+		return result
+	}
+
+	if len(output) > e.config.MaxOutputSize {
+		result.Output = output[:e.config.MaxOutputSize]
+		result.Truncated = true
+	} else {
+		result.Output = output
+	}
+
+	return result
+}
+
+// ExecuteCustomContainerCommand executes an arbitrary command in an LXC container via
+// SSH + pct exec without whitelist validation.
+func (e *Executor) ExecuteCustomContainerCommand(ctx context.Context, host string, containerID int, command string) ExecutionResult {
+	start := time.Now()
+
+	result := ExecutionResult{Command: command}
+
+	ctx, cancel := context.WithTimeout(ctx, e.config.Timeout)
+	defer cancel()
+
+	output, err := e.sshClient.ExecuteContainerCommand(ctx, host, containerID, command)
+	result.Duration = time.Since(start)
+
+	if err != nil {
+		result.Error = fmt.Errorf("execution failed: %w", err)
+		return result
+	}
+
+	if len(output) > e.config.MaxOutputSize {
+		result.Output = output[:e.config.MaxOutputSize]
+		result.Truncated = true
+	} else {
+		result.Output = output
+	}
+
+	return result
+}
+
+// ExecuteCustomVMCommand executes an arbitrary command in a QEMU VM via the guest
+// agent without whitelist validation.
+func (e *Executor) ExecuteCustomVMCommand(ctx context.Context, vm VM, command string) ExecutionResult {
+	start := time.Now()
+
+	result := ExecutionResult{Command: command}
+
+	if e.apiClient == nil {
+		result.Error = fmt.Errorf("API client not configured")
+		result.Duration = time.Since(start)
+		return result
+	}
+
+	ctx, cancel := context.WithTimeout(ctx, e.config.Timeout)
+	defer cancel()
+
+	cmdParts := e.buildGuestAgentCommand(vm, command)
+
+	stdout, stderr, exitCode, err := e.apiClient.ExecuteGuestAgentCommand(ctx, vm, cmdParts, e.config.Timeout)
+	result.Duration = time.Since(start)
+	result.ExitCode = exitCode
+
+	if err != nil {
+		result.Error = fmt.Errorf("execution failed: %w", err)
+		if stderr != "" {
+			result.Output = stderr
+		}
+		return result
+	}
+
+	output := stdout
+	if stderr != "" {
+		output = stdout + "\n--- stderr ---\n" + stderr
+	}
+
+	if len(output) > e.config.MaxOutputSize {
+		result.Output = output[:e.config.MaxOutputSize]
+		result.Truncated = true
+	} else {
+		result.Output = output
+	}
+
+	return result
+}
+
 func (e *Executor) buildGuestAgentCommand(vm VM, command string) []string {
 	switch detectOSFamily(vm.OSType) {
 	case OSFamilyWindows:

internal/plugins/command-runner/ui.go

@@ -79,6 +79,21 @@ func (u *UIManager) showCommandMenu(targetType TargetType, target string, comman
 		u.app.SetFocus(list)
 	}
 
+	// addToList inserts a newly whitelisted command at index 1 (right after "Custom
+	// Command...") so it appears at the top of the whitelist section immediately.
+	addToList := func(cmd string) {
+		desc := GetCommandDescription(cmd)
+		cmdCopy := cmd
+		list.InsertItem(1, cmdCopy, desc, 0, func() {
+			u.handleCommandSelection(targetType, target, cmdCopy, returnToMenu)
+		})
+	}
+
+	// Custom command entry first so it is always visible at the top.
+	list.AddItem("Custom Command...", "Type and run any non-interactive command", '!', func() {
+		u.showCustomCommandForm(targetType, target, returnToMenu, addToList)
+	})
+
 	for _, cmd := range commands {
 		cmdCopy := cmd // Capture for closure
 		description := GetCommandDescription(cmdCopy)
@@ -167,9 +182,9 @@ func (u *UIManager) showParameterForm(targetType TargetType, target, command str
 
 	form.AddButton("Cancel", closeForm)
 
-	// Set input handler for back keys
+	// Only intercept ESC — backspace must remain available for text editing in input fields.
 	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if isBackKey(event) {
+		if event.Key() == tcell.KeyEsc {
 			closeForm()
 			return nil
 		}
@@ -343,6 +358,171 @@ func (u *UIManager) ShowResultModal(result ExecutionResult, onClose func()) {
 	pages.AddPage("commandResult", flex, true, true)
 }
 
+// showCustomCommandForm displays an input form for the user to type an arbitrary command.
+// Commands run non-interactively: sudo requiring a password and interactive programs
+// (vim, top, etc.) will fail with an error from the remote end.
+func (u *UIManager) showCustomCommandForm(targetType TargetType, target string, onReturn func(), onAddToWhitelist func(string)) {
+	pages := u.app.Pages()
+
+	closeForm := func() {
+		pages.RemovePage("customCommandForm")
+		if onReturn != nil {
+			onReturn()
+		}
+	}
+
+	form := tview.NewForm()
+	form.SetBorder(true)
+	form.SetTitle(fmt.Sprintf(" Custom Command on %s (%s) — non-interactive only ", target, targetType))
+
+	var command string
+	form.AddInputField("Command", "", 60, nil, func(text string) {
+		command = text
+	})
+
+	form.AddButton("Execute", func() {
+		cmd := strings.TrimSpace(command)
+		if cmd == "" {
+			return
+		}
+		pages.RemovePage("customCommandForm")
+		u.executeCustomAndShowResult(targetType, target, cmd, onReturn, onAddToWhitelist)
+	})
+
+	form.AddButton("Cancel", closeForm)
+
+	// Only intercept ESC — backspace must remain available for text editing in input fields.
+	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEsc {
+			closeForm()
+			return nil
+		}
+		return event
+	})
+
+	pages.AddPage("customCommandForm", form, true, true)
+}
+
+// executeCustomAndShowResult runs a custom command (no whitelist check) and shows the result.
+// It mirrors executeAndShowResult but calls the custom execution paths.
+func (u *UIManager) executeCustomAndShowResult(targetType TargetType, target, command string, onClose func(), onAddToWhitelist func(string)) {
+	u.showExecutingModal(command)
+
+	go func() {
+		var result ExecutionResult
+		ctx := context.Background()
+
+		switch targetType {
+		case TargetHost:
+			result = u.executor.ExecuteCustomHostCommand(ctx, target, command)
+		case TargetContainer:
+			node, containerID, err := parseContainerTarget(target)
+			if err != nil {
+				result = ExecutionResult{
+					Command: command,
+					Error:   fmt.Errorf("invalid target format: %w", err),
+				}
+			} else {
+				result = u.executor.ExecuteCustomContainerCommand(ctx, node, containerID, command)
+			}
+		case TargetVM:
+			vm, err := u.vmFromTarget(target)
+			if err != nil {
+				result = ExecutionResult{
+					Command: command,
+					Error:   fmt.Errorf("invalid target format: %w", err),
+				}
+			} else {
+				result = u.executor.ExecuteCustomVMCommand(ctx, vm, command)
+			}
+		default:
+			result = ExecutionResult{
+				Command: command,
+				Error:   fmt.Errorf("unsupported target type: %s", targetType),
+			}
+		}
+
+		u.app.QueueUpdateDraw(func() {
+			u.showCustomResultModal(result, targetType, onClose, onAddToWhitelist)
+		})
+	}()
+}
+
+// showCustomResultModal is like ShowResultModal but adds a "Save to Whitelist" button
+// so the user can promote a successful custom command into the session whitelist.
+func (u *UIManager) showCustomResultModal(result ExecutionResult, targetType TargetType, onClose func(), onAddToWhitelist func(string)) {
+	pages := u.app.Pages()
+	pages.RemovePage("executingCommand")
+
+	closeResult := func() {
+		pages.RemovePage("commandResult")
+		if onClose != nil {
+			onClose()
+		}
+	}
+
+	var text strings.Builder
+	fmt.Fprintf(&text, "Command: %s\n", result.Command)
+	fmt.Fprintf(&text, "Duration: %v\n\n", result.Duration)
+
+	if result.Error != nil {
+		fmt.Fprintf(&text, "Error: %v\n\n", result.Error)
+		if result.Output != "" {
+			text.WriteString("Output:\n")
+			text.WriteString(result.Output)
+		}
+	} else {
+		text.WriteString("Output:\n")
+		text.WriteString(result.Output)
+		if result.Truncated {
+			text.WriteString("\n\n[Output truncated]")
+		}
+	}
+
+	textView := tview.NewTextView().
+		SetText(text.String()).
+		SetDynamicColors(true).
+		SetScrollable(true)
+	textView.SetBorder(true)
+	textView.SetTitle(" Custom Command Result ")
+
+	// Build hint line; include whitelist shortcut only when the command succeeded.
+	hintText := " [primary]ESC/Backspace[-] Close | [primary]↑/↓[-] Scroll"
+	if result.Error == nil {
+		hintText += " | [primary]w[-] Save to Whitelist"
+	}
+	hintText += " "
+
+	buttons := tview.NewTextView().
+		SetText(hintText).
+		SetTextAlign(tview.AlignCenter).
+		SetDynamicColors(true)
+
+	flex := tview.NewFlex().
+		SetDirection(tview.FlexRow).
+		AddItem(textView, 0, 1, true).
+		AddItem(buttons, 1, 0, false)
+
+	textView.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if isBackKey(event) {
+			closeResult()
+			return nil
+		}
+		if result.Error == nil && event.Key() == tcell.KeyRune && event.Rune() == 'w' {
+			u.executor.AddToWhitelist(targetType, result.Command)
+			if onAddToWhitelist != nil {
+				onAddToWhitelist(result.Command)
+			}
+			// Update the hint to confirm the save (disable 'w' to prevent duplicates).
+			buttons.SetText(" [green]Saved to whitelist (session only)[-] | [primary]ESC/Backspace[-] Close | [primary]↑/↓[-] Scroll ")
+			return nil
+		}
+		return event
+	})
+
+	pages.AddPage("commandResult", flex, true, true)
+}
+
 // ShowErrorModal displays an error message in a modal
 func (u *UIManager) ShowErrorModal(title, message string, onClose func()) {
 	pages := u.app.Pages()

internal/ui/plugins/commandrunner/plugin.go

@@ -122,6 +122,7 @@ func (p *Plugin) ModalPageNames() []string {
 		"commandResult",
 		"commandError",
 		"executingCommand",
+		"customCommandForm",
 	}
 }