ChatGPTClaudeGrok / X / CursorGemini

DSH plugin approvals: per-session policy and audit pairs

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessUser approvalApprovalPolicyAudit
DSH plugin approvals: four closed outcomes, policy before responders, request fields without tool arguments, and audit pairs inside an open turn.

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

  1. allowed-once authorizes only the operation asked about;
  2. rejected is an explicit refusal;
  3. cancelled means the request was withdrawn;
  4. unavailable means 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-closed unavailable;
  • never — asks nobody, returns rejected deterministically 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)

  1. With default ask in session A and a responder returning allowed-once, assert the tool executes once.
  2. Execute again in the same session and assert the responder is called again with no carry-over quota.
  3. Set never in session B and assert the request settles as rejected with the responder never called.
  4. Register a throwing responder and assert the result is unavailable and the caller denied the operation.
  5. Call request while idle (no open turn) and assert rejection with no new approval/asked in the log.
  6. Abort signal and then let the responder return allowed-once; assert the result is cancelled with 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can DSH plugin allowed-once be reused?

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.

Does a throwing DSH plugin responder allow the operation?

No. DSH plugin fails closed. DSH plugin classifies a missing, non-owning, throwing, or out-of-vocabulary responder as unavailable, and callers reject.

Can a later DSH plugin responder bypass the never policy?

No. DSH plugin enforces never inside the service before waterfall dispatch. DSH plugin gives no responder the request even when registered with prepend.

Do DSH plugin approval audit events enter model history?

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