dsh plugin permissions: what a DSH plugin can and cannot do

A dsh plugin's boundary is decided by three layers: install time only checks allowBuilds authorization, startup time checks which profile it landed in, and run time checks whether tool calls pass the sandbox permission layer and your approval. Plugins run in the same process as dsh, so the capability surface is wide — but the last mile always stays in the permission layer and your hands.

Overview: authorizing one dsh plugin command isn't authorizing everything

To judge what a DSH plugin "can do," split it by time into three layers — conflating them is the most common source of misjudgment. The table lays out what each layer decides (source):

In one sentence: install-time authorization means "the code may run," while run-time authorization means "this operation may land" — neither follows from the other, and they should never be judged together. If you want to know what a plugin is first, read What does dsh plugin mean?.

Capability surface: what a DSH plugin registers through ctx

A plugin is a module exporting an apply function, and ctx is its only interface with the host — the capability surface lives on that interface (source). The main registration entry points are:

This table also explains why plugin permissions equal dsh's permissions: the official tool documentation states that a registered contribution is a same-process typed contribution, not a serialization boundary — the plugin's code simply runs inside the dsh process (source). Its capability floor is therefore high, and the real constraints come from the next two layers.

Install-time boundary: DSH plugin allowBuilds is real execution outside the sandbox

allowBuilds, which a GitHub-source install asks you to approve, is officially defined as "authorizing that package's code to execute on your machine at install time" — outside any sandbox (source). Judge and act in four steps:

1. Confirm which distribution form you're installing — an npm prebuilt package ships with its build output ready, so it works immediately. Expect: no build script authorization needed, the smallest risk surface;
2. Only git sources require approval — pnpm 10 and later refuse to run build scripts of git dependencies by default, so the first add fails and prints the package name that needs approval. Expect: you get an exact package name, not a vague range;
3. Approving means granting execution — add the name to the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-hello-plugin: true

Expect: after re-running add the script executes at install time, and its subsequent behavior is neither predictable nor interruptible; 4. When in doubt, don't authorize — switch to the npm prebuilt version or a tarball instead. Expect: it works immediately with no build authorization.

This boundary is most often misread as "a temporary action during install", when it is in fact real execution: review the source before authorizing, or switch to a more trustworthy distribution form.

Run-time boundary: DSH plugin tool calls pass the permission layer and approval

Registering a tool doesn't mean the tool can run freely — every call passes sandbox tier validation and human approval (source). Four steps along the path of one call:

1. The plugin declares permission policy extension points — the official guidance is not to bury permission logic in the tool body but to use extension points such as tools/pre-execute (allow / deny / ask), ctx.tools.guard() (an irrevocable final denial) and tools/execute (wrapping dispatch, where you can add timeouts and retries) (source). Expect: the tool body stays pure and the policy is centralized and auditable;
2. The call carries a permission tier parameter — to widen access, the request includes sandbox_permissions and must state a reason in justification to pass validation. Expect: the tier may only widen, and a same-level request is treated as an illegal escalation (discussion);
3. The policy asks you when approval is required — for operations subject to approval, the Web UI asks for consent before executing and only continues once approved (source). Expect: the last human gate before execution;
4. An over-reaching request is refused — when the tier is insufficient and escalation conditions aren't met, the call is stopped. Expect: the task visibly "stops and waits for an answer" rather than quietly working around it.

Two corollaries worth remembering: neither a plugin nor a model can bypass approval; and if a dialog appears and you can't tell what the operation does, don't click allow — that is the only veto you get. For repeated sandbox tier rejections, see Sandbox permission escalation rejected.

Three DSH plugin boundaries that get confused

Drawing these lines clearly prevents two opposite mistakes: assuming installing a plugin hands over your computer, or assuming approval blocks everything. The three boundaries separate four objects — plugin, tool, profile and approval (source).

1. Plugin permissions ≠ tool call permissions: no matter how much a plugin registers, each call still passes the tier check and approval; conversely, non-tool code a plugin runs inside apply is in-process code that never goes through the tool approval path. That is exactly why a plugin's origin is itself a judgment call.
2. One plugin ≠ one independent permission set: the profile decides which runtime stack it loads into, and the same plugin installed into web and headless is two independent instances with separate compositions. Installing into the wrong profile is a common cause of "nothing happened after install."
3. Approval is a gate, not an audit: approval stops things before execution, not behavior during a run. For controllability and auditability, prefer plugins with approval gating and audit logs, then verify with the method below.

How to inspect a DSH plugin's boundary: a three-step check

Don't rely on the plugin's description — pin it down with three commands and one entry point. Run them in order (source):

1. Confirm it's in the current profile — dsh plugin --profile web list. Expect: the package name and version appear, meaning it belongs to this runtime stack;
2. Confirm it reached the active composed layers — dsh --profile web --dump-config | grep -n "^# ==". Expect: the plugin's layer shows up among the active ones, not just sitting in the dependency list;
3. Confirm what it registered — compare the registrations it prints at load time (tool names, command names) in the terminal, or check the tool list inside a session. Expect: the registrations match the plugin's description; unexpected extra capabilities are a reason for caution;
4. Check origin and compatibility — open DSH Plugin Hub under Settings → Plugin Market and look at whether the source is npm or GitHub, the compatible DSH version and the verified status. Expect: traceable origin and matching versions before you decide to keep it long term.

The install step also pops a confirmation dialog that lays out the exact install command and the source in front of you.

Rather than reverse-engineering what a plugin registered with commands afterwards, check its source, version and command in the Hub at install time — the confirmation dialog lists all of them. Visit https://dsh-plugin.org/ to learn more.

Sources: Building a tool (official docs), Your first plugin (official docs), Packaging and installing plugins (official docs), official Quickstart, Discussion #1149