ChatGPTClaudeGrok / X / CursorGemini

DSH plugin Agent ownership: creation, handles, interception

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessAgent ownershipAgentHandleagent/pre-step
Create agents through ctx.agents; only the caller gets a handle. Covers create vs resume, the setup window, handle actions, and pre-step interception.

In DSH plugin, an Agent is not an object you construct casually; it is a resource with ownership. Who calls create, who receives the handle, and where interception happens are three separate questions. Blur them, and you get plugins that can obtain an Agent but cannot tear it down, or that register a hook that never fires.

Three identities: creator, owner, holder

Creation, lifecycle ownership, and session identity are distinct, and mixing them guarantees leaks across plugins.(source)

IdentityWhat it meansWhere it appears
CreatorThe caller that triggered constructionctx.agents.create() or resume()
OwnerThe party holding the handle and able to disposeAgentHandle.dispose()
Structural ownerThe provider behind the factory or service APIProvider unload drains its live handles
Session identityOwnership of the durable logagent.id (SessionId)

One easily missed detail from the core page: agent/ and agent-loop/ are a pair. The former declares the Agent interface, the live registry, initiator scoping, and the agent/* vocabulary; the latter is the only concrete implementation. Extension plugins depend on agent, including when they need to spawn one, and never on agent-loop, which keeps the loop replaceable.

scope/ is the only non-service package in that group: zero dependencies, exposing createScope, scopeOf, and scopeTarget. If you only need per-agent isolation, you never touch the loop.

create and resume differ by more than “new”

Both return an AgentHandle, but one builds a session and the other adopts a persisted one.(source)

  1. create() — builds a fresh session and agent under a caller-supplied SessionId. Use it for new tasks, subagent derivation, and one-off experiments.
  2. resume() — loads a persisted session first, then restores the agent in the new process. Use it after restarts, crashes, or cross-session continuation.

CreateAgentOptions carries everything needed before publication:

  • meta — validated cwd, fork lineage, isSeeded, source classification, delegation depth, and agentPreset;
  • inheritedEventCount — the exact fork cut;
  • seed — an optional replay prefix;
  • agentOptions — per-agent routing and output settings;
  • signal — a cancellation signal valid only during creation;
  • setup — the pre-publication assembly callback.

ResumeAgentOptions is the persisted counterpart with only resumeSessionId, agentOptions, signal, and setup. That is why the two cannot be interchanged: the resume path has no meta and no fork cut, because its session is already on disk.

setup is the only pre-publication window

Anything that must apply from the very first prompt has to register through setup's agentCtx.(source)

The documented order is: Session persisted and session/created complete, then setup(agentCtx, agent), then agent registration, then agent/created, then the first prompt assembly.

Two consequences follow. First, registrations made through agentCtx exist before agent/created and before the first assembly; registering later misses that first assembly. Second, setup may return a synchronous commit that runs immediately before publication.

Rollback semantics belong in your design: a rejected setup, a throwing commit, or an owner dispose all remove the Session while preserving recovered pending input and stored events. Failure never leaves half an agent, and never deletes the input you just recovered.

What the handle can actually do

The Agent is the programming surface; it offers delivery and observation, not arbitrary state mutation.(source)

  1. Delivery — send(message, target, wakeup) exposes routing; followup(), steer(), and inject() are fixed presets.
  2. Cancellation — cancel(cause, options) clears queued and steering work and aborts the active turn; whenIdle() waits for whole-agent quiescence.
  3. Maintenance — runMaintenance(task) runs a non-turn task from true idle while public status stays idle.
  4. Durable projections — inbox.nextTurn, inbox.nextStep, and model.current() / select().

Three easy misreads: status is only idle or running, and disposal emits agent/disposed rather than adding a third status; running covers the driver's drain interval and can span consecutive turns, so it does not prove a particular turn is open; followup() returns no handle, and its MessageId identifies inbox insertion, claim, and discard facts, not assistant output.

initiator is attribution, not authorization

The initiator carried by ctx.agents is that exact Agent instance, not a copied identity.(source)

  • currentInitiator() reads the inherited initiator and returns undefined outside a boundary;
  • requireInitiator() throws when no boundary is active, for helpers contractually below a driver;
  • withInitiator(agent, operation) runs an operation under one exact Agent and preserves the returned value;
  • withoutInitiator(operation) hides inherited attribution, useful for lazy shared timers, queue pumps, and pool maintenance.

Treat the warning as a hard rule: presence proves neither liveness nor authorization. Subjects and owners must be explicit, as must identity at worker, process, persistence, and wire boundaries. A queue or wire receiver may establish the boundary only after validating explicit identity and resolving a live Agent, and withInitiator does neither.

Interception happens at pre-step, not on the handle

The only official channel for “does this step run, and with which messages” is agent/pre-step.(source)

The payload carries the exclusively claimed batch messages, the proposed turn and step, and the turn's cancellation signal. The decision has two forms:

ts
type PreStepDecision =
  | { kind: 'reject' }
  | { kind: 'enter'; messages: UserMessage[]; startsRequestSeries?: true }

reject opens no step. enter provides the full batch appended after step/start. Messages omitted from the final decision stay removed, while input inserted after the claim waits for later processing. The first proposal runs inside an open turn before any step, and tool continuations may submit an empty claimed batch between steps.

Two other decision points are easy to confuse. agent/request-error runs after a failed step closes and before its turn closes; a listener may repair durable state while the turn signal is alive, return { kind: 'retry' } without calling next() to take over recovery, or return undefined to leave the failure terminal. agent/turn-stopping runs when a turn has no tool or steering follow-up, before the final steering drain.

Validating a minimal ownership chain

Run create → deliver → reject → finish once, and assert each handle state; it beats re-reading the interfaces.(source)

  1. Call create() with a fixed SessionId, register a probe service in setup, and assert it resolves before agent/created.
  2. Read handle.agent.status, expect idle, call followup(), expect running.
  3. Await whenIdle() and assert status is idle with an empty inbox.nextTurn.
  4. Return reject once from agent/pre-step and assert there is no step/start, no step consumed, and no batch restored.
  5. Call handle.dispose() and assert ctx.agents.get(id) no longer returns the agent and agent/disposed fired.

If step 5 fails, you are probably holding a bare Agent from get(id), which has no dispose. That is the boundary worth remembering.

If turn and step ordering is still fuzzy, read Agent lifecycle first; for package boundaries, see plugin spec.

One line to close: create through create or resume, hand the handle only to the caller, assemble only in setup, and intercept only at pre-step; everywhere else you observe, not replace.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can a DSH plugin dispose an Agent from ctx.agents.get?

No. In DSH plugin, dispose lives only on the AgentHandle returned at creation. get(id) returns a bare Agent for delivery and observation, and the handle is exposed only to the consumer owner that created it.

Are create and resume interchangeable in DSH plugin?

No. DSH plugin create builds a fresh session under a caller-supplied SessionId, while resume loads a persisted session first. CreateAgentOptions and ResumeAgentOptions carry different fields, so they cannot be mixed.

Does a throwing setup leave half an Agent behind?

No. DSH plugin rolls back the transaction and removes the Session. A rejected setup, a throwing commit, and an owner dispose share that path, while recovered pending input and stored events are preserved.

Is a rejected pre-step batch an error in DSH plugin?

No. DSH plugin treats reject as “do not open a step.” The claimed batch stays removed and the turn spends no step, which is a normal admission result rather than a failure.

Related Terms

AgentHandle
AgentHandle is the owned handle returned by ctx.agents.create and resume, containing the agent and a dispose() that only the owner holds.— packages/core/agent/src/index.ts
AgentFactory
AgentFactory is the creation interface behind the registry, registered by agent-loop through ctx.agents.setFactory(), so consumers never depend on the loop package.— DeepSeek Harness reference - Core
initiator
The initiator is the process-local Agent carried by ctx.agents for causal attribution; its presence proves neither liveness nor authorization.— DeepSeek Harness reference - Core
PreStepDecision
PreStepDecision is the return type of agent/pre-step, with only reject and enter forms; enter carries messages appended after step/start.— DeepSeek Harness reference - Core

Sources