[FEATURE] Guaranteed cross-platform substrate for plugin scripts — documented toolbelt + a blessed script runner

Status Open
Maintainer reply None cached
Activity 0 comments · opened Jul 23, 2026

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. python3 on 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)

  1. 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.)

  1. 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.

  1. 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).

View original on GitHub ↗