DSH plugin approvals: per-session policy and audit pairs
"Why does this session run the tool directly while that one prompts" is answered by the last policy event in the session log. DSH plugin's approval seam answers exactly one question: may this specific operation continue? There are four outcomes, and only one permits it.
The approval seam answers one question
It neither executes nor renders; it produces a closed result.(source)
dsh-user-approval owns the shared request and result vocabulary, the ctx.approval dispatch service, the approval/request responder waterfall, the log-only audit event pair, and the per-session ask and never policies.
UI channels can supply human responders; the ACP automation bridge supplies one-shot machine decisions for the agents it owns. Callers such as dsh-tools and dsh-tool-bash consume the closed result and reject anything that is not allowed-once.
That "reject everything else" rule sets the tone for the whole design: the default state is denial, not permission, and every uncertainty lands on the denying side.
Identity and outcome: four closed values
allowed-once is a one-shot authorization, not a switch.(source)
Each request gets a fresh ApprovalRequestId. The branded type pairs approval/asked with approval/decided and prevents approval ids from being swapped with tool call ids or agent session ids.
ApprovalOutcome is closed: allowed-once, rejected, cancelled, unavailable.
allowed-onceauthorizes only the operation asked about;rejectedis an explicit refusal;cancelledmeans the request was withdrawn;unavailablemeans no responder was usable.
Callers deny all three of the latter. A missing, non-owning, throwing, or out-of-vocabulary responder yields unavailable, never permission.
Per-session policy: policy first, responders second
never takes effect before dispatch, so responders never see the request.(source)
ApprovalPolicy decides what happens before interactive responders run:
ask(default) — delegates to the composed responder chain; with no responder on the chain it falls back to the fail-closedunavailable;never— asks nobody, returnsrejecteddeterministically for every ask, and dispatches to no responder.
The effective value is the last approval/policy event in the session log, falling back to service configuration. Consumers read it through ctx.approval.effectivePolicy(session); setApprovalPolicy(session, policy) is the only write path, so replay can rebuild the override.
Both policies contribute their full current meaning to the cache-safe runtime context snapshot. A sourced user/message is persisted and model-visible input; when approval state changes, a fresh complete snapshot is appended after the retained history without touching the system/message node carrying the rendered system prompt.
Approval requests deliberately omit tool arguments
Responders attach to the already-streamed call via callId rather than re-rendering a copy that could drift.(source)
ApprovalRequest identifies the agent and tool operation precisely enough for routing and auditing the question, but intentionally omits tool arguments. Those arguments were already streamed into the tool call, and duplicating them would drift.
Field duties: agent is the agent being asked for, used for routing (UI responders answer only for agents they own) and for delivering audit events into that agent's session log; toolName serves display and audit; optional callId lets the UI attach the prompt to the already-streamed tool call; optional reason is audit text; optional signal withdraws the question on abort — the request settles as cancelled immediately and late answers from still-waiting responders are discarded.
Optional displayReason passes a caller-provided localized string to the interface while reason remains audit text. Do not mix them: one is for people, the other for logs.
Dispatch and audit must sit inside an open turn
The audit pair must be bracketed by log commit and replay boundaries, so an idle ask is rejected.(source)
ctx.approval.request(req) requires the requesting session to be inside an unfinished turn. It appends approval/asked, obtains a result, appends the matching approval/decided, then completes with that result.
The never policy is enforced inside the service before waterfall dispatch, so even a responder registered later with prepend cannot bypass it.
A responder returns a result when it takes the request and otherwise calls next() to delegate; the first responder occupies the single decision slot.
Audit events write the log only and never enter the model transcript. What the model sees is the caller-derived tool result plus the current runtime context snapshot. Disposing the service removes its context contribution, while responder listeners bind independently to their owning plugin through effects.
Every failure path closes
No failure path ever becomes permission.(source)
- an aborted signal yields
cancelled; - a missing or throwing responder yields
unavailable; - a responder returning a value outside the vocabulary is normalized to
unavailable; - an idle ask rejects before appending any event.
One transactional constraint remains: if either audit append fails before the commit point, the request still rejects, because returning an unrecorded decision would break the asked/decided pair. Conversely, the Session absorbs observer failures after commit, so an authoritative append neither fails the request nor suppresses the matching audit event.
Remember the asymmetry: pre-commit failure fails everything, post-commit failure affects nothing.
Verification: two sessions, different policies
Verify dispatch paths and audit persistence, not just the outcome value.(source)
- With default
askin session A and a responder returningallowed-once, assert the tool executes once. - Execute again in the same session and assert the responder is called again with no carry-over quota.
- Set
neverin session B and assert the request settles asrejectedwith the responder never called. - Register a throwing responder and assert the result is
unavailableand the caller denied the operation. - Call
requestwhile idle (no open turn) and assert rejection with no newapproval/askedin the log. - Abort
signaland then let the responder returnallowed-once; assert the result iscancelledwith the late answer discarded.
If a responder is still called in step 3, never was placed after the waterfall, which makes the policy cosmetic.
For combining approvals with user questions, see approval and user questions; for permission preset configuration, see permissions and approval settings.
One line to close: of four outcomes only one permits, policy runs before responders, requests carry a callId and no arguments, audit pairs must land inside an open turn, and every failure closes.
FAQ
No. DSH plugin's allowed-once authorizes only the operation asked about. DSH plugin issues a fresh ApprovalRequestId per request, so the next operation must go through approval again.
No. DSH plugin fails closed. DSH plugin classifies a missing, non-owning, throwing, or out-of-vocabulary responder as unavailable, and callers reject.
No. DSH plugin enforces never inside the service before waterfall dispatch. DSH plugin gives no responder the request even when registered with prepend.
No. DSH plugin audit events are log-only. DSH plugin gives the model the caller-derived tool result and runtime context snapshot, never the approval event itself.
Related Terms
- ApprovalRequestId
- ApprovalRequestId is a fresh branded id issued per request, pairing approval/asked with approval/decided.— packages/interaction/user-approval/src/index.ts
- ApprovalOutcome
- ApprovalOutcome is the closed approval result: allowed-once, rejected, cancelled, or unavailable.— packages/interaction/user-approval/src/index.ts
- ApprovalPolicy
- ApprovalPolicy is the session-level policy where ask delegates to responders and never rejects deterministically without dispatch.— packages/interaction/user-approval/src/index.ts
- ApprovalRequest
- ApprovalRequest is an in-process read-only permission question with agent, toolName, optional callId, reason, and signal, but no tool arguments.— packages/interaction/user-approval/src/index.ts
Sources
- DeepSeek Harness reference - User approval· deepseek-ai
- packages/interaction/user-approval/src/index.ts· deepseek-ai