[FEATURE] Guaranteed cross-platform substrate for plugin scripts — documented toolbelt + a blessed script runner
Problem
Plugins ship executable scripts (skills' scripts/, hooks, MCP stdio servers), but the
environment they run in guarantees nothing beyond "some bash exists" — and even that is
undocumented. Every plugin author rediscovers the same failures:
- No interpreter is guaranteed.
python3on stock Windows is a Microsoft Store stub
that errors; node is no longer implied since the native installer replaced npm as the
default; the docs guarantee neither.
- PATH is not the user's PATH. In the Windows desktop app the Bash tool missed
WinGet's Links directory, so the model prefixed export PATH=…; to every command —
which breaks allowed-tools pattern matching and turns a pre-approved flow into a
permission storm.
- OS integration is per-platform trivia. Clipboard is wl-paste/xclip vs pbpaste vs
Get-Clipboard; file-open is xdg-open vs open vs os.startfile; BSD vs GNU stat.
We maintain a published plugin (claude-ppq) and
coping required: uv-locating launcher shims (current PATH → login shell → Windows
registry User+Machine Path via powershell/cygpath), Store-stub-safe python detection,
three clipboard branches plus a .ps1 twin of a bash launcher, and a 3-OS CI matrix with
model-in-the-loop e2e tests to keep it all true. That's ~200 lines of substrate per
plugin that the platform could provide once.
Request (tiered)
- Document the guaranteed toolbelt. Specify what the Bash tool environment always
contains per platform (bash version, coreutils, curl, git) and make
git-bash-on-Windows an explicit contract. (Kimi Code CLI already fails-fast without
Git Bash on Windows; Claude Code relies on it silently.)
- Bless a portable script runner. Ensure one cross-platform, dependency-resolving
runner is always available and on PATH for plugin scripts — uv is the obvious
candidate (single static binary, PEP 723 single-file scripts with inline deps; already
the de-facto convention in skill ecosystems). Even just "Claude Code installs/locates
uv and exposes ${CLAUDE_UV}" would delete the worst per-plugin boilerplate.
- Longer term: a sandboxed plugin runtime. None of the major harnesses has solved
this — Codex CLI and Kimi Code are bring-your-own-runtime like Claude Code; opencode
embeds Bun and runs plugins in-process but with zero isolation ("use Docker"). A
sandboxed runtime (WASM/isolate with a capability API: fs-scoped, fetch, clipboard,
open) would be a genuine differentiator rather than parity.
Why this matters beyond one plugin
The Claude plugin format is becoming a de-facto standard: Codex CLI's plugin system
exports CLAUDE_PLUGIN_ROOT for compatibility and both Codex and Kimi converge on~/.agents/skills/. The format's portability story currently ends at "markdown is
portable, scripts are your problem" — fixing that at the platform level lifts every
plugin in the directory at once.
Related: #80696 (desktop app not arming skill allowed-tools grants — the PATH failure
mode above is what models fall back to when pre-approval breaks).