ChatGPTClaudeGrok / X / CursorGemini

DSH plugin permission presets: auto, custom, and set

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessPermission presetsautocustom
DSH plugin permission presets bundle sandbox mode and approval policy: reserved names, fixed auto registration, derived custom, and set write order.

"I switched the preset but behavior did not change" usually means the new preset shares the same knob pair as the old one, and only those two underlying events take effect. DSH plugin's permission preset layer owns no enforcement policy; it bundles sandbox/mode and approval/policy into named options. Understand the bundling and post-switch behavior becomes explainable.

A preset is a named bundle of two knobs

It does not enforce policy; it writes knobs.(source)

The permission preset layer (ctx.permissionPresets) in dsh-permission-presets bundles two independent enforcement knobs — sandbox mode (sandbox/mode) and approval policy (approval/policy) — into named presets the client can expose as a single Permissions selector.

The config table owns defaults for future sessions, while the fixed registerAuto(admit) hook lets the Auto review integration publish current-session-only options for the lifetime of one effect.

The layer is optional and owns no enforcement policy: prompt narration and replay still read each knob's folded result, and extra enforcement belongs to Auto review. So a "preset" is not a permission system but a shortcut that combines two systems.

The table and two reserved names

custom and auto cannot be configured; trying to configure them fails at load.(source)

PresetSpec contains sandbox, approval, and optional name and description for client display. The default table ships two entries:

  • workspace-write — workspace-write + ask;
  • danger-full-access — danger-full-access + never.

Config has presets and defaultPreset. When defaultPreset is omitted, the preset matching the composed sandbox and approval defaults is used.

The service requires an isolating ctx.shell executor and ctx.approval, and configuration errors fail at plugin load: an entry named custom or auto throws, and composing on a non-isolating bash executor (one without the sandboxMode capability fact) throws too, because presets bundle a sandbox mode.

That load-time failure is far easier to debug than a runtime error: when the plugin will not start, check preset names and executor capabilities first.

Auto is a fixed current-session registration

Auto cannot be "registered as another preset"; only the fixed hook publishes it.(source)

The Auto integration calls registerAuto(admit) within its own effect lifetime. The service fixes the auto identity and the danger-full-access plus ask combination, and recorded Auto selections also match the never policy fixed for delegated child sessions.

Display ownership is split cleanly: the shipped client's locale dictionary owns Auto's label and description, while configured presets' display information stays with the Host. Callers cannot publish other presets through a generic contribution API.

Auto is ordered after configured presets, never enters the permission.defaultPreset settings schema, and disappears when the effect disposes.

admit is a synchronous callback running before an Auto choice modifies the Session and before the stored Auto Session is published. So a missing or shutting-down integration cannot rewrite persisted identity — the safety boundary for automatic approval during session recovery.

Catalog changes emit no session events

The catalog is a process-level snapshot, and the session projection holds only currentValue.(source)

Registering or removing Auto emits a payload-free permission-presets/catalog-changed notification. Process-level consumers must subscribe first, then call catalog(), re-reading the full option list after each notification.

The permissions Session projection contains only currentValue, so catalog changes append no Session event, publish no Session projection frame, and change no Session sequence. That keeps "the client menu changed" entirely separate from "session history changed."

current and the derived custom

custom is a computed current value, not a selectable item.(source)

current(session) derives the effective preset from the required permissions projection. That unit folds the session's sandbox mode, approval policy, and recorded choice; missing values inside state fall back to the executor's configured mode and the approval service's configuration, then to ask. A missing projection key fails explicitly.

Selection order: prefer a still-matching choice (including a recorded Auto choice under a never approval policy), then the first matching configured entry, otherwise CUSTOM_PRESET ('custom').

custom is only a derived value: clients may display it as the current value, but it is never a switch target and never appears in event payloads.

names lists configured presets in declaration order, then Auto while the integration is alive. catalog() returns those entries as a process-level snapshot. optionOf(name) builds an option for an available entry (label falling back to the key) or for the derived custom, and throws for any other name.

Clients merge catalog and Session projection: custom may be marked as the current value but never becomes a catalog entry.

Switch order: record the choice, then changed knobs

set writes conditionally; re-selecting the active preset writes nothing.(source)

set(session, name) runs in order:

  1. resolve the preset, throwing for an unknown name;
  2. run Auto admission when applicable;
  3. append a log-only permission/preset event when name is not yet the effective preset;
  4. write through each knob's own setter (setSandboxMode and setApprovalPolicy), only when that knob's effective value changes.

Within one turn, the choice event precedes the knob events; re-selecting the currently effective preset appends nothing.

permission/preset is durable, log-only user intent: it never enters the model transcript, and model-visible consequences come from the knob events through their own consumers. Its purpose is concrete — two presets may share one knob combination, and without this event current() could not preserve which one the user chose.

The permissions projection folds that choice together with the two knob events and preserves the session/end-seed boundary that distinguishes an empty recovery seed from a new session; replay needs no catch-up state or raw log rescan. A restored auto choice requires a live Auto registration before the agent publishes.

Verification: switch presets twice

Cover "only changes are written" and "shared combinations remain distinguishable."(source)

  1. Read current() in a new session and assert it is the default preset, not custom.
  2. Call set(session, 'danger-full-access') and assert permission/preset appears first, followed by both knob events.
  3. set the same preset again and assert no new events appear.
  4. Configure two presets with identical sandbox and approval, switch back and forth, and assert current() reports the last name.
  5. Manually change the approval policy to a combination matching no preset and assert current() returns custom.
  6. Remove the Auto integration, read catalog() again, and assert the auto entry is gone while the session sequence is unchanged.

If step 4 returns the first match instead of the last choice, permission/preset is not being folded into the projection.

For how presets relate to approval policy, see permissions and approval settings; for Auto deadlocks, see permission preset auto deadlock.

One line to close: a preset bundles two knobs, neither custom nor auto is configurable, auto only comes from the fixed hook, custom is derived only, and set writes changes with the choice event first.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can you configure a DSH plugin preset named auto?

No. DSH plugin reserves both custom and auto. DSH plugin throws while loading when a config entry is named custom or auto, so configuration mistakes never reach runtime.

Can DSH plugin custom be a switch target?

No. DSH plugin's custom is only a derived value. DSH plugin lets clients display it as the current value, but it is never a switch target and never appears in event payloads.

Does re-picking the active DSH plugin preset append events?

No. DSH plugin appends nothing in that case. DSH plugin appends permission/preset only when name is not yet the effective preset, and writes a knob only when its effective value actually changes.

Do DSH plugin catalog changes alter the session sequence?

No. DSH plugin's permissions projection holds only currentValue. DSH plugin catalog changes append no session event, publish no projection frame, and leave the session sequence untouched.

Related Terms

PresetSpec
PresetSpec is one preset's sandbox and approval bundle, with sandbox, approval, and optional display name and description.— packages/interaction/permission-presets/src/index.ts
registerAuto
registerAuto is the fixed current-session Auto registration hook, publishing auto options only for the caller effect's lifetime.— packages/interaction/permission-presets/src/index.ts
CUSTOM_PRESET
CUSTOM_PRESET is the derived value returned when no available preset matches the knob combination, rendered as custom.— packages/interaction/permission-presets/src/index.ts
permission/preset
permission/preset is the durable log-only user intent event that preserves the choice when presets share a knob combination.— packages/interaction/permission-presets/src/index.ts

Sources