DeepSeek Harness tool cards: presentCall in a DSH plugin

A DSH plugin tool's output travels two paths: output.render returns the model-visible content, while "cards" are a separate concern declared through pure presentation projections and the optional presentCall / presentResult (source). This article covers what each method returns, how to choose among the five card kinds, and the three hard rules that break things when violated; the defineTool and output.schema contract is in the tool execute contract, and settings-page cards (host half + browser half) are in plugin UI development, so neither is repeated here.

presentCall in a DSH plugin: the three card kinds a pending card can return

presentCall(args) returns a ToolCallView for the pending phase (the PENDING card), covering the period before the tool produces a result (source). Three kinds are available:

1. generic (default) — { card: 'generic', title, kind?, rawInput?, content?, locations? }. Set kind for an icon (read / search / …); set locations: [{ path, line? }] to mark the files the tool touches so capable editors can follow or jump.
2. terminal — { card: 'terminal', title, description?, cwd? }. The call is itself a shell command: title is the command and description renders above the terminal card (as tool-bash does).
3. diff — { card: 'diff', title, diffs, locations? }. diffs: [{ path, oldText, newText }] renders an inline diff card (oldText: null for a new file, as in tool-fs write / edit).

Note there is no search: discovery results exist only after execute, so a discovery call's pending state can only stay a generic card.

presentResult in a DSH plugin: completed cards and five card details

presentResult(args, { content, isError, meta? }) returns the completed card, and the search and web details are the easiest to miss (source).

1. generic — provides an optional title and content.
2. terminal — provides raw output and optional exit metadata; each UI renders its own view or a fallback based on capability.
3. diff — provides the applied hunks, usually derived by output.presentationMeta and carried through persisted result.meta so replay can reproduce them. Change-making tools keep the diff result because the completed view replaces the pending card.
4. search — discovery results rebuilt from persisted result.meta: matches grouped by file (shape: 'matches', grep) or a flat path list (shape: 'paths', glob), plus truncated / total so the UI never presents a truncated result as complete. This view carries no result text (a UI without a search card falls back to the raw result content), and there is no search call view (tool-fs-search grep / glob).
5. web — a completed web retrieval distinguished by kind: 'search' | 'fetch' (structured search sources or a fetch summary), derived from result.meta; it carries no body copy, so a UI without web capability falls back to the raw result content (tool-web web_search / web_fetch).

The three hard rules for DSH plugin tool cards

The official reference singles out the rules that "break things when violated," and all three must hold (source).

1. Pure functions — these methods run both during live streaming and during session-log replay, so they must be pure functions of args (plus result): no I/O, no reading session state, no clocks or randomness. diffs derive from args only (write uses oldText: null because the call-time presenter has no prior file contents); session context comes from the UI adapter, not the tool. If you find yourself fetching old file contents or the working directory inside presentCall, stop: that belongs to persisted result metadata or the adapter, not the presenter.
2. UI formats do not enter the model result — fenced console blocks, diffs, and relativized paths should not enter the canonical value or Native content just to serve the UI. output.render owns model-visible natural language; presentationMeta and the card presenters own replayable UI state; the terminal result view carries raw output and the adapter adds fallback formatting as needed.
3. defineTool soft-validates the presentation path — malformed or legacy-log arguments make the wrapper return undefined (the generic fallback) instead of throwing, because presentation must never crash replay.

One more architectural discipline: neutral vocabulary lives in dsh-tools, and tools never import UI or transport types; host and client runtimes map each card to their own view. To compare reference implementations, find tool plugins on the DSH Plugin Hub (dsh-tool-fs for generic / diff, dsh-tool-bash for terminal); for the output.render and canonical-value contract see the tool execute contract, and for how tools are consumed inside UI plugins see plugin UI development.