DSH plugin permission presets: auto, custom, and set
"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:
- resolve the preset, throwing for an unknown name;
- run Auto admission when applicable;
- append a log-only
permission/presetevent whennameis not yet the effective preset; - write through each knob's own setter (
setSandboxModeandsetApprovalPolicy), 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)
- Read
current()in a new session and assert it is the default preset, notcustom. - Call
set(session, 'danger-full-access')and assertpermission/presetappears first, followed by both knob events. setthe same preset again and assert no new events appear.- Configure two presets with identical sandbox and approval, switch back and forth, and assert
current()reports the last name. - Manually change the approval policy to a combination matching no preset and assert
current()returnscustom. - 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.
FAQ
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.
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.
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.
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
- DeepSeek Harness reference - Permission presets· deepseek-ai
- packages/interaction/permission-presets/src/index.ts· deepseek-ai