9.6 KiB
description, kind
| description | kind |
|---|---|
| Channel-neutral one-shot approval seam for users and maintainers composing answerers, setting policy, or debugging fail-closed permission decisions. | package-reference |
@deepseek-ai/dsh-user-approval
English | 中文
Summary
dsh-user-approval lets a sensitive tool action pause for a one-shot allow/reject decision: ctx.approval.request(req) asks the composed answerers whether one specific action may proceed and returns allowed-once, rejected, cancelled, or unavailable. Missing, non-owning, or throwing answerers fail closed to unavailable, and a grant applies only to the requested action. A per-session policy — ask (the default) or never — decides what happens before any answerer runs: ask delegates to the composed answerers, never rejects every request deterministically without prompting anyone. Each request is recorded in the requesting session's audit log, and the model sees only the asking consumer's tool outcome plus the current policy in the runtime-context snapshot. UI channels provide human answerers; the ACP automation bridge answers for its own agents.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Compose this service when sensitive tool actions should pause for a human or machine decision instead of running unconditionally. The tools pipeline and the sandboxed bash tool route their ask decisions through this seam and fail closed when it is absent, so interactive deployments mount it with at least one answerer.
Composing answerers
Answerers are approval/request waterfall listeners: return an outcome to answer for an owned agent, or call next() to delegate. Agent-scoped listeners receive only that agent's requests, and a deployment composes one terminal answerer — sibling listener order is not a policy-priority mechanism. Without a terminal answerer, requests resolve unavailable and fail closed; the service itself never prompts a human.
Setting the policy
The effective policy is the one set for the session, falling back to the configured default. ask (the default) delegates to the composed answerers; never rejects every request deterministically before interactive dispatch — the strict headless stance for CI and unattended runs.
- name: '@deepseek-ai/dsh-user-approval'
config:
policy: ask
| Field | Default | Meaning |
|---|---|---|
policy |
ask |
Default for sessions without an approval/policy override |
The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc. setPolicy(agent, policy) switches a live agent and queues a "changed by the user" message for its next model step; setApprovalPolicy(session, policy) is the direct durable write path used by session initialization.
Requesting a decision
request(req) names the agent, tool, optional call id and reason, and an abort signal. It requires an open turn: an idle or between-turn caller throws before auditing anything. Aborting withdraws the question — the request settles cancelled and a late answer is discarded. A failure that prevents either audit append from committing rejects instead of returning an unlogged decision.
What the model and user see
The model sees only the asking consumer's eventual tool outcome — allowed, rejected, cancelled, or unavailable — plus the current policy in the runtime-context snapshot; the audit events and the human permission UI are not model context. A never switch is announced to the model by a sourced user message, and both policies contribute their complete current meaning to the snapshot.
Understand the implementation
Implementation internals — click to expand
The observable behavior is covered in Use this package; this section explains dispatch, policy enforcement, and the audit path.
Source map
| File | Role |
|---|---|
src/index.ts |
ApprovalService: request dispatch, policy fold and write path, runtime-context contribution |
src/types.ts |
ApprovalRequestId brand and outcome types |
src/invariant.ts |
Invariant companion pairing approval/asked with approval/decided inside an open turn |
Dispatch
decide() races the answerer waterfall against the request signal and contains every answerer failure: a throwing listener fails the question closed to unavailable, and a rogue non-vocabulary return is normalized to unavailable. The never policy is enforced inside the service before waterfall dispatch, so a listener registered later with prepend cannot bypass the deterministic rejection. The request must be turn-enclosed because the turn is the durable log's commit/replay boundary — a bare event between turns is indistinguishable from a crash tail.
Policy and the runtime-context snapshot
The system-prompt contribution approval:policy states the complete current meaning of the effective policy — ask with its fail-closed consequence, or never with its non-escalation consequence — after retained history, so switching policy appends a new full snapshot instead of rewriting the stable request header. setPolicy() also injects a sourced user message announcing the change for the next step.
Audit
request() appends approval/asked with the request identity and tool, then approval/decided with the closed outcome; the exact appended fields live in src/index.ts. Both are log-only; the invariant validates the pair by id within one open turn and the closed outcome vocabulary.
Further Exploration
Read these pages when the package-level contract is not enough. They move from the approval vocabulary to the consumers and the design rationale.
- Approval subsystem reference — the shared request/outcome vocabulary and the
ctx.approvalcordis surface. - Approval seam Agent Note — design rationale for the seam.
- Sandbox Agent Note — how the sandboxed bash tool consumes approvals for escalated retries.
- Interaction group map — adjacent permission preset and question packages.
Model Experience
Current approval policy context
What the model sees
The first request and each effective policy change append a full runtime-context snapshot after retained history. Under ask, the approval contribution states that configured answerers may be consulted and absence fails closed. Under never, it states the deterministic rejection and non-escalation consequence. Unchanged requests retain the earlier snapshot without adding another message.
Ask-policy contribution
Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.
Never-policy contribution
Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).
Token effect
One concise context message on the first request and on an effective change; unchanged requests add no duplicate policy tokens.
KV Cache effect
Append-only after retained history. An ask/never switch preserves the stable system and conversation prefix instead of rewriting the first wire message.
Tool outcome
What the model sees
approval/asked and approval/decided are log-only. The model sees only the asking consumer's eventual allowed, rejected, cancelled, or unavailable tool outcome; the human permission UI is not context.
Token effect
Zero duplicate audit tokens. A rejection may replace a normal tool result with a small retained error, while an allowance leaves the consumer's ordinary result.
KV Cache effect
Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
Known Limitations and Deferred Work
These limits define when the seam is a poor fit or needs special composition care. They are current package constraints, not a general permission comparison.
- Requests are valid only inside an open turn — an idle or between-turn caller throws before auditing; a durable out-of-turn approval workflow is deferred.
- Only one-shot grants exist — the outcome vocabulary has
allowed-oncebut noallow-always, remembered rule, revocation, or grant store; session policy is onlyask/never. - The request carries no tool arguments — an answerer sees the tool name, reason, and optional call id; the ACP machine channel requires a call id and delegates requests without one.
- No built-in answerer — headless or incompletely composed deployments resolve
unavailableand fail closed; the service itself never prompts a human.
Dev Note
Working context for maintainers — click to expand
None.