DSH plugin commands: definitions, results, and discovery
Commands are the capability most often mistaken for a special tool: they never reach the model, produce no tool result, and no turn wraps them. DSH plugin's user command registry service threads discovery, parsing, and execution into a separate channel. Understand that channel and both "registered but invisible" and "executed but untraceable" become explainable.
Commands skip the model and go through the registry
Execution targets the exact agent and creates no model message.(source)
dsh-commands provides the user command registry service that lets interactive adapters discover plugin-owned commands and execute them against the exact agent without creating model messages.
Layering works like skills: definitions from ordinary contexts are global; commands injected through an agent context register child definitions that shadow global ones for that agent. So "the same command behaves differently under different agents" can be design rather than conflict.
Definitions: few fields, firm boundaries
recordInput decides whether raw input gets written a second time.(source)
CommandDefinition contains:
- optional
definitionId— stable plugin-owned identity, omittable when no client behavior keys off it; name— lowercase command name without a leading slash;description— human-readable summary for discovery UIs;- optional
input— an unstructured input descriptor with ahintand anattachmentsflag; - optional
recordInput— whethercommand/runrecordsrawInput, defaulting totrue; setfalsewhen domain events already own that payload to avoid duplicating it in the session log; handler— executes against the receiving agent without sending the command to the model.
The registry validates and freezes an effective definition detached from the original registration object, so mutating your object after registering does not affect what took effect.
One easily missed registration entry: registerFileReceiptResolver(resolver) registers the single staging file receipt resolution authority and returns a disposer removing it. Commands that want staged files need that chain, or attachment admission fails for missing storage.
Attachment admission is enforced in execute
A combinator may pre-block, but the real decision lives in the service.(source)
When input.attachments is true, the handler receives admitted durable blocks and owns all later syntax decisions, including rejecting subcommands that cannot use attachments. When omitted or false, the executor rejects calls carrying attachments, and capable combinators also refuse submission before dispatch.
All three failures settle as an error result before the handler runs: attachments sent to a command that did not declare input.attachments, missing attachment storage, and an exceeded image cap. A validation rejection starts no attachment write, while a storage failure may leave only an inaccessible content-addressed object awaiting lazy collection.
That ordering matters: admit first, execute second. A handler never sees half-written attachment state.
Invocation and results: straight to the UI
rawInput keeps separators and suffix verbatim, with no re-parsing.(source)
CommandInvocation has five fields: commandId (the pairing id already written into this command/run), agent (the exact agent receiving the command), rawInput (the complete text right after the registered name, separator whitespace included), attachments, and signal.
Cancellation belongs to the adapter, which passes the exact target agent. Results render directly in the UI rather than becoming tool results or session events.
CommandResult has two forms: success (optional text and optional sourceEventSeq) and error (required text).
sourceEventSeq is optional and success-only. When present it points at an earlier non-command event in the receiving session log; command/done persists the same reference so clients can merge the command lifecycle with that domain projection without parsing text or relying on adjacency.
That solves a practical pain point: a command's result may be a rendering, or it may be "look at that event." A reference is more stable than copied text.
Lifecycle log: run before, done after
Both events are appended directly with no turn wrapping them, but order is still a promise.(source)
execute resolves and runs a known command without sending it to the model. A resolved command's lifecycle is recorded: command/run is appended before the handler is invoked, and command/done after settlement — a throwing or aborted handler settles with kind: 'error'.
Both are direct log-only appends with no turn wrapping them, and persistence drains them at ordinary checkpoints. Admission failures (syntax error or unknown name) record nothing, because they never reached a handler.
Two failure semantics must be separated: a failed command/run append fails the execution explicitly, while on a handler failure path a failed command/done append is absorbed so the handler's own error remains the reported failure.
Discovery versus parse views
parseCommand judges syntax; find judges availability.(source)
After scope resolution, adapters receive immutable handler-free descriptors called CommandDescriptor. list(agent) returns name-sorted descriptors after scope shadowing; find(agent, name) returns the shadowed definition or the global one.
parseCommand() returns a ParsedCommand (only name and rawInput) before registry resolution, so syntactically valid input can still point at an unavailable command. Completion lists and execution availability are therefore not the same data.
commands/change is an unfiltered registry notification: global or scoped changes may affect any UI view, so it is unfiltered, and observer failures are absorbed rather than allowed to veto the change.
Verification: one command with arguments
Cover registration, visibility, attachment admission, and log order.(source)
- Register a command named
deployand assertlist(agent)includes it with the right description. - Register a same-name command in one agent's context and assert that agent sees the shadowed version while others still see the global one.
- Call
executewith the full linedeploy prod --fastand assertrawInputpreserves theprod --fastseparator whitespace. - Send an image to a command without
input.attachmentsand assert the handler never ran and the result is an error. - Assert
command/runappears beforecommand/donein the log with no turn wrapping them. - Call
executewith a nonexistent command name and assertundefinedwith no new log events.
If the handler still runs in step 4, attachment admission was pushed inside the handler, breaking the admit-then-execute guarantee.
For registration and prompt integration, see user command registration; for how commands relate to approvals, see approval policy.
One line to close: commands never reach the model, recordInput only controls log duplication, attachments are admitted before execution, results go straight to the UI, run/done are turn-free but ordered, and valid syntax is not executability.
FAQ
No. DSH plugin commands execute directly against the exact agent. DSH plugin interaction adapters use them to discover plugin-owned commands and execute them without creating model messages.
Only commands declaring input.attachments. DSH plugin enforces admission in execute: undeclared attachments, missing attachment storage, or an exceeded image cap all settle as an error before the handler runs.
No. DSH plugin's parseCommand judges syntax only. DSH plugin lets syntactically valid input point at an unavailable command, and only registry resolution reveals executability.
No. DSH plugin presents results directly to the UI. DSH plugin writes only the command/run and command/done lifecycle events to the log, and no turn wraps them.
Related Terms
- CommandDefinition
- CommandDefinition is a plugin-authored command registration: optional identity, name, description, input descriptor, recordInput, and handler.— packages/interaction/commands/src/index.ts
- CommandInvocation
- CommandInvocation is what a handler receives: commandId, agent, rawInput, attachments, and a cancellation signal.— packages/interaction/commands/src/index.ts
- CommandResult
- CommandResult renders directly in the dispatching UI and has only success and error forms.— packages/interaction/commands/src/index.ts
- ParsedCommand
- ParsedCommand is a syntactically valid slash command before registry resolution, carrying only name and rawInput.— packages/interaction/commands/src/index.ts
Sources
- DeepSeek Harness reference - User commands· deepseek-ai
- packages/interaction/commands/src/index.ts· deepseek-ai