ChatGPTClaudeGrok / X / CursorGemini

DSH plugin subagents: names, handles, and result reads

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessSubagentsPersistent enumerationSubagentResult
DSH plugin subagents: capability checks before activation, name versus Session id, messaging rules, catalog projection, and result fields.

"My subagents vanished after restart" and "I sent a message but state did not change" are the same mistake: treating a name as identity. DSH plugin uses Session id as the unique execution identity, with names as model-facing references only. Separate those two and persistent enumeration plus messaging gain stable semantics.

One activation API, capabilities checked first

Every backend goes through startActivation, and capability flags reject unsupported options before creation.(source)

A unified activation API manages local conversations and external executions, with the subagent tree owning ancestor relations, run ownership, and communication. All backends use startActivation: capability flags validate the requested options, prepareContinuable selects local Agent creation, and start selects a single external execution.

SubagentCapabilities has four flags: agentOptions, agentPreset, outputSchema, and depthLimit. The manager checks each capability the request uses before preparing a local child or launching an external execution. depthLimit governs maxDepth, and the other flag names map one-to-one onto SubagentStartRequest fields.

Mind the cwd resolution rule: relative paths resolve against the parent's currently effective directory, and omitting it captures that directory at admission. Local child Sessions keep the parent's original project, while cold resume keeps the directory state recorded in their log.

Model-facing tools use parent delivery; Workflow and code mode consumers may await the caller result without injecting extra messages into the parent agent. When a historical child's descriptor is unavailable, it remains discoverable with mode: 'unknown' but gains no ability to continue.

Spec and handle: disposal covers this activation only

dispose() releases this activation, never a later resume.(source)

SubagentActivationSpec adds five things beyond the start request: provider, label (retained in cataloged child members), name, optional childId, signal, and delivery.

The name rules are concrete: unique among the parent's children, 1 to 32 lowercase letters, digits, or hyphens, starting with a letter, and never lead; omitted names take the first free agent-N. childId is a reservable identity for local children, while external backends allocate their own ids.

delivery decides delivery semantics: parent notifies the model, caller returns the result only to the caller. Local children always enter the parent catalog regardless of delivery.

SubagentActivation exposes childId, name, optional messageId, result, and dispose(). result settles once teardown is final and notification has been sent; dispose() stops and releases only this activation, reporting teardown failure as a rejection without overwriting a captured result.

Names are references; Session ids are identity

resolveName only resolves; it grants no permission.(source)

Session id remains the unique execution identity for routing, authorization, persistence, and task ownership; names are model-facing references. SubagentActivation.name is the child's full name: when every level from the root carries a name, listDescendants() rows carry it as path.

namesOf(agent) reports online members and their direct creators' names, with the root named lead. resolveName(caller, name, signal) returns the Session id for lead or a full name; text absent from the tree is returned verbatim as a Session id, while a slash path pointing at no member fails with AGENT_NAME_NOT_FOUND.

That last sentence matters: the caller authorizes the resolution result, and resolution itself grants nothing. "The name resolved" never means "you may operate it."

Messaging and interrupts need exact live identity

Cross-branch messaging works, offline only cold-resumes, and external executions reject further input.(source)

sendMessage requires an exactly live sender and a target Session id in the same root tree. The root and continuable members may message across branches; admission revalidates sender and root. A running target receives Steer; only an offline target is cold-resumed, and its creating ancestors may stay offline. External executions reject further input.

Notification paths are limited too: local and external executions report final text, structured output, diagnostics, and status only to a still-live direct creator; caller delivery suppresses those notifications.

Disposal scope must be distinguished: drainDescendants awaits the whole tree, while the activation receipt's dispose() releases only that one execution.

Interrupts have explicit authorization shapes: user is a trusted host operation; Remote callers need permission on the target Session; ancestor carries the exact live Agent among the target's creating ancestors.

Persistent enumeration and backend handles

The catalog records membership, not execution state.(source)

The parent-owned subagentCatalog projection lists all local children plus parent-delivered external children. Caller-delivered external executions leave membership and result collection to the caller; local workflow children remain discoverable after completion.

External entries carry mode: 'external' and can neither open a child Session nor accept later messages. The catalog records membership at creation and carries no execution state. list_agents shows the root and reachable continuable descendants, with activity as running or inactive.

On the result side, SubagentResult serves programmatic consumers. The activation registry retains external backend handles until release completes.

Cleanup failure is handled carefully: a captured execution result is never overwritten — the activation result and parent notification keep it, dispose() rejects, and the live subagent/end event reports error. So when dispose fails, do not also mark the result failed.

How to read result fields

output and structured are independent channels, and diagnostic needs its own presentation.(source)

  • output — the child's final assistant output, taken from the last non-empty assistant message, skipping empty messages including usage-only ones. Without a non-empty message it uses the accumulated assistant text stream, and [] if neither exists.
  • structured — the structured result produced after outputSchema was requested and satisfied. Requesting it guarantees nothing: when a child fails or ends without a valid capture, the provider may end with stopReason: 'error'.
  • diagnostic — provider-written non-assistant failure detail, which must exclude tool input, file contents, environment values, credentials, and raw protocol payloads, and is capped at 4096 UTF-8 bytes. Consumers must present it apart from output.
  • stopReason — a merge-extensible end reason with known values completed, aborted, error, max-tokens, and refusal.

A non-completed reason means output may be partial. The tool layer therefore maps non-completed results to isError tool results rather than reporting half-written output as success.

Message provenance is distinguished as well: AgentMessageSource has kind: 'agent-message', meaning content sent by another agent, while SubagentSettledMessageSource has kind: 'subagent-settled', a runtime settlement note. Merging the two makes a transcript attribute words the child never wrote.

Verification: create, restart, enumerate

Cover name resolution, offline recovery, and result partitioning.(source)

  1. Create a child named reviewer with startActivation and assert both activation.name and childId are usable.
  2. Call resolveName(caller, 'reviewer') and assert a Session id; then use a nonexistent slash path and assert AGENT_NAME_NOT_FOUND.
  3. After a restart, call list_agents and assert the child is still visible with state inactive.
  4. Send it a message and assert cold resume happens; restart again and assert messaging still works.
  5. Interrupt a running child and assert the target receives Steer rather than starting a new turn.
  6. Let the child end with max-tokens and assert the correct stopReason, output treated as partial, and diagnostic presented separately.

If step 4 fails, first check whether an external execution was used by mistake — external backends reject further input, which is a different problem from "the subagent does not exist."

For subagent integration and delegation, see subagent providers and subagent delegation configuration; for persistence-side recovery boundaries, see the persistence seam.

One line to close: check capabilities first, dispose this activation only, names are not identity, offline means cold resume, the catalog holds no state, and result and cleanup failure must be read separately.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can a DSH plugin subagent name serve as identity?

No. DSH plugin uses Session id as the unique execution identity. DSH plugin's name is only a model-facing reference; routing, authorization, persistence, and ownership always use the Session id.

Can DSH plugin message a subagent that is offline?

Not directly. DSH plugin only cold-resumes an offline target. DSH plugin's sendMessage requires an exactly live sender and a target Session id in the same root tree, and external executions reject further input.

Does a DSH plugin structured result always exist?

No. A DSH plugin request schema never guarantees output. DSH plugin lets a provider end with error when the child fails or ends without a valid capture, leaving structured absent.

Does DSH plugin cleanup failure overwrite the run result?

No. DSH plugin keeps the captured result. DSH plugin preserves it in the activation result and parent notification, rejects from dispose, and reports error on the live subagent/end event.

Related Terms

SubagentCapabilities
SubagentCapabilities are optional backend capability flags: agentOptions, agentPreset, outputSchema, and depthLimit.— packages/subagent/subagent/src/types.ts
SubagentActivation
SubagentActivation is the receipt of one managed child execution: childId, name, optional messageId, result, and dispose.— packages/subagent/subagent/src/types.ts
SubagentResult
SubagentResult is a child run's terminal outcome: output, optional structured, optional diagnostic, and stopReason.— packages/subagent/subagent/src/types.ts
subagentCatalog
subagentCatalog is the parent-owned projection listing all local children plus parent-delivered external children, recording membership at creation.— DeepSeek Harness reference - Subagent

Sources