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 <self-exe> _spawn-ai <spec-path> as the launcher command, where <self-exe> is the absolute path of the currently-running binary (so multi-binary installs call back into the same binary instead of resolving gw via PATH). execute reads the spec, unlinks it, chdir’s, and execvp’s the real tool — the pane shell only ever parses ASCII (or quoted ASCII for paths with spaces).

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.

resolve_last_for_cwd

Resolve the last persisted spec path for the current working directory’s worktree. Reads <git-dir>/gw-spawn-last.json. Errors are prefixed with spawn-ai: so the entrypoint can print them verbatim.

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.