DSH Plugin Interaction: Approval, Question, Command, Tool?
Once a plugin has to deal with people, choosing the wrong entry point costs more to fix than writing the wrong logic. Approval, question, command, and tool all look like ways to "have the user do something", yet their initiator, their responder, and their blocking behavior are entirely different. In a DSH plugin each path has closed semantics, and mixing them turns a flow into something neither testable nor auditable.
A DSH plugin decision table for four entry points
Start with who initiates and who answers, and the choice usually makes itself. (source)
| Entry | Initiated by | Answered by | Blocking | Enters model context |
|---|---|---|---|---|
| Approval | Before a tool runs | User or automated bridge | Blocks that operation | No, audit only |
| Question | Inside a tool or command | User | Timed, may be answered later | Yes, as a user message |
| Command | User | Plugin handler | No | No |
| Tool | Model | Plugin execute | Yes, consumes a turn | Yes |
The two rightmost columns are the ones people forget. Approval produces nothing the model can see, so "the user approved" has to be relayed through the tool result. Questions enter the conversation history, so they should never carry pure authorization.
Approval: the DSH plugin path to one-time consent
Approval means "this time", never "from now on". (source)
ApprovalOutcome is closed over four values, and only allowed-once lets the work proceed. A responder that is absent, does not handle the request, throws, or returns something outside the vocabulary is recorded as unavailable and treated as a refusal.
Three things to get right:
- Ask before acting -- approval belongs in front of the operation, not as an audit note afterwards.
- Do not attach arguments -- the request deliberately omits tool parameters and links through
callIdto a call already streamed to the user, which avoids re-render drift. - No turn, no approval -- requesting approval while idle fails outright, because the audit pair must live inside an open turn.
Session policy also matters: never rejects before dispatch, so the responder is never consulted. Never build a flow that assumes the user will approve.
Questions: DSH plugin information, not permission
A question answers "which one", not "may I". (source)
Questions support structured options, free text, and multiple selections; answers carry label strings rather than indexes. A timed question waits inside its window and returns pending when the window closes.
Remember what pending means: the question is still answerable. It is not an empty answer, a refusal, a confirmation, or a grant. Treating pending as "the user gave up" is the usual first step toward mishandling late replies.
Good fits: an ambiguous parameter value, a choice between two approaches, a sentence of context only the user can supply. Bad fits: permission checks (approval) and defaults the model should infer (tool parameter defaults).
Commands: DSH plugin user-initiated, no turn consumed
When the user knows what they want, a command is more direct than a tool. (source)
A command runs against the exact agent, creates no model message, and is wrapped in no turn. Registration declares a name, a description, and optional input; results go straight to the UI and only command/run and command/done reach the log.
Two boundaries are worth knowing. Attachment admission is enforced inside execute, so a command that did not declare input.attachments fails before its handler runs when sent one. And rawInput keeps separators and suffixes, so parsing is the command's job -- the framework will not split arguments for you.
Good fits: actions the user explicitly wants, debugging entries, queries needing immediate feedback. Bad fits: requests that require the model to understand natural language.
There is also a quiet benefit: a command consumes no turn. Ten user queries are ten lightweight calls and do not lengthen the conversation, whereas doing the same through a tool carries the schema and the result on every turn.
Tools: DSH plugin model-initiated, one turn each
Most "let the model do something" requirements end up as a tool. (source)
The model invokes a tool during a turn. defineTool derives and validates parameters from parameters, execute returns the canonical value declared by output.schema, and output.render turns it into model-facing content.
The relationship with the other three is composition, not substitution. A tool can request approval before a dangerous step, ask a question when an argument is missing, and expose a manual entry point as a command.
Order matters when composing: gather information, then obtain consent, then act. Reverse the last two and the thing the user approved may not be the thing that runs.
DSH plugin composition and three failure patterns
Misuse has recognizable symptoms, and recognizing them is most of the fix. (source)
- Question instead of approval -- the user clicks "agree", but no audit record exists and nothing proves the grant was one-time.
- Tool error instead of question -- the model retries three times with a different guess each round while the user watches three failures.
- Command instead of tool -- the user must memorize syntax for arguments the model could have inferred from context.
The mirror images are just as common: approval used where a value is needed, a command doing work that requires model judgment, a tool spent on a purely deterministic operation.
All six share one root cause: the entry point does not match the initiator. Do not ask which one is nicer; ask who starts this step and who should answer it.
Verification: one requirement, four implementations
Implement "delete a batch of files" four ways and the differences surface immediately. (source)
- As a tool: the model calls it with a path list, approval runs first, and only
allowed-onceactually deletes. - As a question: ask which batch to delete first, assert a structured choice comes back and lands in the conversation history.
- As a command: the user types the command name, assert no model message is created and the result goes straight to the UI.
- As session policy: set
neverand assert the request is rejected before dispatch, with the responder never invoked. - Chained: question for parameters, then approval for consent, and assert both close independently and the
callIdmatches the same call.
If step 1 deletes without an audit entry, approval was placed after execution. If step 5 approves one call and runs another, the approval request carried parameters instead of linking by callId.
Session policy details are in approval and session policy; timeouts and late replies in question timeouts; registration in user commands.
One line to close: consent goes to approval, values go to questions, user-initiated actions go to commands, model-initiated work goes to tools -- the four compose but never substitute, and the test is always who starts, who answers, and whether a record must remain.
FAQ
Approval: a DSH plugin approval releases the operation only on allowed-once and treats every other outcome as refusal, which maps exactly onto may I do this once. A tool that simply fails offers no channel for the user to consent, so an irreversible delete should obtain one-time authorization first.
Ask when you need information from a person, using the DSH plugin question seam. The DSH user-interaction seam supports structured options, free text, and timed windows, and returns the user's actual choice. Making a tool fail so the model guesses turns one clear question into several failed rounds and often guesses wrong.
A DSH plugin command wins when the user starts it and the model has no role. A DSH command runs against an exact agent, creates no model message, and consumes no turn. Tools are for cases where the model must judge arguments or read context.
Yes: DSH plugin approval and questions chain sequentially, each closed on its own. In DSH a question returns a choice and approval returns a one-time release; collect the parameters first, then request approval, and associate it with the call by callId so the user approves what actually runs.
Related Terms
- ApprovalOutcome
- ApprovalOutcome is a closed set; only allowed-once permits the operation, while rejected, cancelled, and unavailable are all handled as refusal by the caller.— DeepSeek Harness Reference - User Approval
- AskUserQuestionIntent
- AskUserQuestionIntent is the presentation intent for a question, limited to plan-review and approval; it changes the display, not how the answer is encoded.— DeepSeek Harness Reference - User Interaction
- CommandDefinition
- CommandDefinition is the registration object for a user command, with a name, description, optional input description, and handler; running it creates no model message.— DeepSeek Harness Reference - User Commands
- ToolDefinition
- ToolDefinition is the registration object for a tool, with a model-facing schema, a required output declaration, and an execute function that the model invokes during a turn.— DeepSeek Harness Reference - Tools
Sources
- DeepSeek Harness Reference - User Approval· deepseek-ai
- DeepSeek Harness Reference - User Interaction· deepseek-ai