Module spawn_spec 

Spawn-spec — safely launch AI tools without shell escape hazards.

Prompts with quotes/$/backticks/newlines break when re-quoted through AppleScript/wezterm/tmux send-text layers. Instead, materialize writes argv+cwd to a temp file and returns gw _spawn-ai <path> as the launcher command. execute reads the spec, unlinks it, chdir’s, and execvp’s the real tool — the pane shell only ever parses ASCII.

The emitted line intentionally does NOT use exec so that when it is fed into an already-running interactive shell (e.g. wezterm cli send-text, iTerm AppleScript write text, tmux send-keys into a session pane), the shell survives the AI tool’s exit and keeps the tab/pane open at its prompt. Launchers that run the line as the pane’s sole process via bash -lc <line> (tmux-window, tmux-pane-, zellij-) are unaffected either way: their pane still closes when the AI tool exits because the bash -lc invocation has nothing else to do.

Structs

SpawnSpec

Constants

SPEC_VERSION

Functions

execute

Execute a spawn spec. Never returns to the caller:

materialize

Write spec to a 0600 tempfile in the system temp dir and return (shell_line, spec_path). shell_line is safe to hand to any launcher.

materialize_in_dir

Test seam — write into an explicit directory.

read_spec

Parse a spec file, rejecting unsupported versions and empty argv. All errors are prefixed with spawn-ai: so the entrypoint can print them verbatim without duplicating the prefix.

sweep_stale

Best-effort removal of stale gw-spawn-*.json temp files from the system temp directory. Intended to run once at gw startup. All errors are swallowed — this is a safety net, not a correctness mechanism.