Add OSC 51 elisp eval from shell

Allow shell scripts to call whitelisted Elisp functions via OSC 51
escape sequences (same protocol as vterm). Includes ghostel_cmd
shell helper, ghostel-eval-cmds whitelist, and documentation.

Author: dakra

README.md

@@ -141,9 +141,48 @@ Soft-wrapped newlines are automatically stripped from copied text.
 - Prompt navigation via OSC 133 — jump between prompts with `C-c C-n` / `C-c C-p`
 - Title tracking (buffer renamed from OSC 2)
 - OSC 8 hyperlinks — clickable URLs in terminal output (click or `RET` to open)
+- Elisp eval from shell via OSC 51 — call whitelisted Emacs functions from shell scripts
 - OSC 52 clipboard support (opt-in, for remote sessions)
 - `INSIDE_EMACS` and `EMACS_GHOSTEL_PATH` environment variables
 
+### Calling Elisp from the Shell
+
+Shell scripts running inside ghostel can call whitelisted Elisp functions
+via the `ghostel_cmd` helper (provided by the shell integration scripts):
+
+```sh
+ghostel_cmd find-file "/path/to/file"
+ghostel_cmd message "Hello from the shell"
+```
+
+This uses OSC 51 escape sequences (the same protocol as vterm).  Only
+functions listed in `ghostel-eval-cmds` are allowed.
+
+Default whitelisted commands:
+
+`find-file`, `find-file-other-window`, `dired`, `dired-other-window`, `message`.
+
+Add your own with:
+
+```elisp
+(add-to-list 'ghostel-eval-cmds '("magit-status-setup-buffer" magit-status-setup-buffer))
+```
+
+Example shell aliases (add to your `.bashrc` / `.zshrc`):
+
+```sh
+if [[ "$INSIDE_EMACS" = 'ghostel' ]]; then
+    # Open a file in Emacs from the terminal
+    e()   { ghostel_cmd find-file-other-window "$@"; }
+
+    # Open dired in another window
+    dow() { ghostel_cmd dired-other-window "$@"; }
+
+    # Open magit for the current directory
+    gst() { ghostel_cmd magit-status-setup-buffer "$(pwd)"; }
+fi
+```
+
 ### Color Palette
 
 The 16 ANSI colors are defined as Emacs faces inheriting from `term-color-*`:
@@ -164,18 +203,19 @@ individual faces with `M-x customize-face`.
 
 ## Configuration
 
-| Variable                      | Default             | Description                            |
-|-------------------------------|---------------------|----------------------------------------|
-| `ghostel-shell`               | `$SHELL`            | Shell program to run                   |
-| `ghostel-shell-integration`   | `t`                 | Auto-inject shell integration          |
-| `ghostel-buffer-name`         | `"*ghostel*"`       | Default buffer name                    |
-| `ghostel-max-scrollback`      | `10000`             | Maximum scrollback lines               |
-| `ghostel-timer-delay`         | `0.033`             | Redraw delay in seconds (~30fps)       |
-| `ghostel-kill-buffer-on-exit` | `t`                 | Kill buffer when shell exits           |
-| `ghostel-enable-osc52`        | `nil`               | Allow apps to set clipboard via OSC 52 |
-| `ghostel-prompt-reapply-on-redraw` | `nil`          | Re-apply prompt markers after full redraws |
-| `ghostel-keymap-exceptions`   | `("C-c" "C-x" ...)` | Keys passed through to Emacs           |
-| `ghostel-exit-functions`      | `nil`               | Hook run when the shell process exits  |
+| Variable                           | Default             | Description                                |
+|------------------------------------|---------------------|--------------------------------------------|
+| `ghostel-shell`                    | `$SHELL`            | Shell program to run                       |
+| `ghostel-shell-integration`        | `t`                 | Auto-inject shell integration              |
+| `ghostel-buffer-name`              | `"*ghostel*"`       | Default buffer name                        |
+| `ghostel-max-scrollback`           | `10000`             | Maximum scrollback lines                   |
+| `ghostel-timer-delay`              | `0.033`             | Redraw delay in seconds (~30fps)           |
+| `ghostel-kill-buffer-on-exit`      | `t`                 | Kill buffer when shell exits               |
+| `ghostel-eval-cmds`                | `(see above)`       | Whitelisted functions for OSC 51 eval      |
+| `ghostel-enable-osc52`             | `nil`               | Allow apps to set clipboard via OSC 52     |
+| `ghostel-prompt-reapply-on-redraw` | `nil`               | Re-apply prompt markers after full redraws |
+| `ghostel-keymap-exceptions`        | `("C-c" "C-x" ...)` | Keys passed through to Emacs               |
+| `ghostel-exit-functions`           | `nil`               | Hook run when the shell process exits      |
 
 ## Commands
 
@@ -269,7 +309,7 @@ powering Neovim's built-in terminal.
 | Alternate screen              | Yes       | Yes     |
 | Shell integration auto-inject | Yes       | No      |
 | Prompt navigation (OSC 133)   | Yes       | Yes     |
-| Elisp eval from shell         | No        | Yes     |
+| Elisp eval from shell         | Yes       | Yes     |
 | Tramp-aware directory         | No        | Yes     |
 | OSC 52 clipboard              | Yes       | Yes     |
 | Copy mode                     | Yes       | Yes     |

etc/ghostel.bash

@@ -60,3 +60,15 @@ __ghostel_original_prompt_command="${PROMPT_COMMAND:+$PROMPT_COMMAND}"
 PROMPT_COMMAND="__ghostel_wrapped_prompt_command"
 
 trap '__ghostel_preexec' DEBUG
+
+# Call an Emacs Elisp function from the shell.
+# Usage: ghostel_cmd FUNCTION [ARGS...]
+# The function must be in `ghostel-eval-cmds'.
+ghostel_cmd() {
+    local payload=""
+    while [ $# -gt 0 ]; do
+        payload="$payload\"$(printf '%s' "$1" | sed -e 's|\\|\\\\|g' -e 's|"|\\"|g')\" "
+        shift
+    done
+    printf '\e]51;E%s\e\\' "$payload"
+}

etc/ghostel.fish

@@ -36,3 +36,16 @@ end
 function __ghostel_preexec --on-event fish_preexec
     printf '\e]133;C\e\\'
 end
+
+# Call an Emacs Elisp function from the shell.
+# Usage: ghostel_cmd FUNCTION [ARGS...]
+# The function must be in `ghostel-eval-cmds'.
+function ghostel_cmd
+    set -l payload ""
+    for arg in $argv
+        set arg (string replace -a '\\' '\\\\' -- $arg)
+        set arg (string replace -a '"' '\\"' -- $arg)
+        set payload "$payload\"$arg\" "
+    end
+    printf '\e]51;E%s\e\\' "$payload"
+end

etc/ghostel.zsh

@@ -37,3 +37,15 @@ __ghostel_preexec() {
 
 precmd_functions=(__ghostel_save_status __ghostel_prompt_start __ghostel_osc7 "${precmd_functions[@]}" __ghostel_prompt_end)
 preexec_functions=(__ghostel_preexec "${preexec_functions[@]}")
+
+# Call an Emacs Elisp function from the shell.
+# Usage: ghostel_cmd FUNCTION [ARGS...]
+# The function must be in `ghostel-eval-cmds'.
+ghostel_cmd() {
+    local payload=""
+    while (( $# )); do
+        payload="$payload\"${1//\\/\\\\}\" "
+        shift
+    done
+    printf '\e]51;E%s\e\\' "$payload"
+}

ghostel.el

@@ -333,6 +333,18 @@ exit event string."
   :type 'hook
   :group 'ghostel)
 
+(defcustom ghostel-eval-cmds '(("find-file" find-file)
+                                ("find-file-other-window" find-file-other-window)
+                                ("dired" dired)
+                                ("dired-other-window" dired-other-window)
+                                ("message" message))
+  "Whitelisted Emacs functions callable from the terminal via OSC 51.
+Each entry is (NAME FUNCTION) where NAME is the string sent from
+the shell and FUNCTION is the Elisp function to invoke.
+All arguments are passed as strings."
+  :type '(alist :key-type string :value-type function)
+  :group 'ghostel)
+
 (defcustom ghostel-enable-osc52 nil
   "Allow terminal applications to set the clipboard via OSC 52.
 When non-nil, programs running in the terminal can copy text to the
@@ -1296,6 +1308,20 @@ the last non-whitespace+whitespace boundary (e.g. after `$ ' or `# ')."
 
 ;;; Callbacks from native module
 
+(defun ghostel--osc51-eval (str)
+  "Handle an OSC 51;E command from the terminal.
+STR is the payload after the E sub-command.
+Parses the command and arguments, looks up the command in
+`ghostel-eval-cmds', and calls it if whitelisted."
+  (let* ((parts (split-string-and-unquote str))
+         (command (car parts))
+         (args (cdr parts))
+         (entry (assoc command ghostel-eval-cmds)))
+    (if entry
+        (apply (cadr entry) args)
+      (message "ghostel: unknown eval command %S (add to `ghostel-eval-cmds' to allow)"
+               command))))
+
 (defun ghostel--osc52-handle (_selection base64-data)
   "Handle an OSC 52 clipboard set request.
 SELECTION is the target (e.g. \"c\" for clipboard).

src/emacs.zig

@@ -302,6 +302,7 @@ pub const Sym = struct {
     @"ghostel--detect-urls": Value,
     @"ghostel--set-cursor-style": Value,
     @"ghostel--update-directory": Value,
+    @"ghostel--osc51-eval": Value,
     @"ghostel--osc52-handle": Value,
     @"ghostel--osc133-marker": Value,
     @"ghostel--flush-output": Value,

src/module.zig

@@ -176,6 +176,7 @@ fn fnWriteInput(raw_env: ?*c.emacs_env, _: isize, args: [*c]c.emacs_value, _: ?*
 
     // Scan for OSC sequences that libghostty-vt discards.
     extractAndSetPwd(term, raw);
+    extractOsc51(env, raw);
     extractOsc52(env, raw);
     extractOsc133(env, raw);
 
@@ -227,6 +228,23 @@ const OscScanner = struct {
     }
 };
 
+/// Scan data for OSC 51;E elisp eval sequences.
+/// OSC 51 format: ESC ] 51 ; E <quoted-args> (ST | BEL)
+/// Passes the payload (after 'E') to ghostel--osc51-eval for dispatch.
+fn extractOsc51(env: emacs.Env, data: []const u8) void {
+    var scanner = OscScanner{ .data = data, .prefix = "\x1b]51;" };
+    while (scanner.next()) |match| {
+        const payload = match.payload;
+        if (payload.len < 2) continue;
+        // Sub-command must be 'E'
+        if (payload[0] != 'E') continue;
+        _ = env.call1(
+            emacs.sym.@"ghostel--osc51-eval",
+            env.makeString(payload[1..]),
+        );
+    }
+}
+
 /// Scan data for OSC 7 sequences and set the terminal PWD.
 /// OSC 7 format: ESC ] 7 ; <url> (ST | BEL)
 fn extractAndSetPwd(term: *Terminal, data: []const u8) void {

test/ghostel-test.el

@@ -819,6 +819,28 @@
           (kill-buffer buf)
           (kill-buffer other))))))
 
+;; -----------------------------------------------------------------------
+;; OSC 51 elisp eval
+;; -----------------------------------------------------------------------
+
+(ert-deftest ghostel-test-osc51-eval ()
+  "Test that OSC 51;E dispatches to whitelisted functions."
+  (let* ((called-with nil)
+         (ghostel-eval-cmds
+          `(("test-fn" ,(lambda (&rest args) (setq called-with args))))))
+    (ghostel--osc51-eval "\"test-fn\" \"hello\" \"world\"")
+    (should (equal '("hello" "world") called-with))))
+
+(ert-deftest ghostel-test-osc51-eval-unknown ()
+  "Test that unknown OSC 51;E commands produce a message."
+  (let ((ghostel-eval-cmds nil)
+        (messages nil))
+    (cl-letf (((symbol-function 'message)
+               (lambda (fmt &rest args) (push (apply #'format fmt args) messages))))
+      (ghostel--osc51-eval "\"unknown-fn\" \"arg\"")
+      (should (car messages))
+      (should (string-match-p "unknown eval command" (car messages))))))
+
 ;; -----------------------------------------------------------------------
 ;; Runner
 ;; -----------------------------------------------------------------------
@@ -831,7 +853,9 @@
     ghostel-test-update-directory
     ghostel-test-filter-soft-wraps
     ghostel-test-prompt-navigation
-    ghostel-test-sync-theme)
+    ghostel-test-sync-theme
+    ghostel-test-osc51-eval
+    ghostel-test-osc51-eval-unknown)
   "Tests that require only Elisp (no native module).")
 
 (defun ghostel-test-run-elisp ()