DeepSeek Harness (DSH) native subagent control plane only provides send_message, interrupt_agent, and list_agents, lacking interfaces for deleting or releasing subagents. This causes one-shot subagents and expired continuable subagents to continuously accumulate in the Web UI list. The dsh-plugin-subagent-delete plugin fills this gap by providing model-callable tools based on ownership checks, as well as optional HTTP routes.

Installation and Activation

Run the following command in the terminal to add the plugin to the Web configuration file:

dsh plugin --profile web add github:heiheiha798/dsh-plugin-subagent-delete

After installation, restart the configuration profile and start a new session. The session will have three tools.

Core Features

list_subagents

Lists descendant subagents of the calling session. The returned results include the subagent ID, label, mode (one-shot | continuable), status (running | inactive), depth, parent ID, and whether it has children.

// 获取所有后代
list_subagents({})

// 仅获取正在运行的
list_subagents({ activity: "running" })

// 仅获取一次性子代理
list_subagents({ mode: "one-shot" })

delete_subagent

Permanently deletes a subagent session and removes it from the Web UI list. The operation includes verifying that the target is a descendant of the calling session, stopping a live agent or draining a resident Continuable Activation, detaching the session from the session manager, deleting the log directory on disk, cleaning up database records, and updating workspace accounting information.

// 永久删除指定 ID 的子代理
delete_subagent({ subagent_id: "<id>" })

// 递归删除（目标及其所有后代）
delete_subagent({ subagent_id: "<id>", recursive: true })

release_subagent

Stops and releases a subagent while preserving its records and conversation history. This allows the subagent to be resumed later via send_message.

// 释放而不删除
release_subagent({ subagent_id: "<id>" })

// 递归释放
release_subagent({ subagent_id: "<id>", recursive: true })

Automatic Web UI Refresh

DSH does not natively provide a refresh path for subagent deletion. The plugin works around this limitation by emitting an ephemeral marker session and leveraging the official prepare → enter → announce → detach lifecycle interface. The client component listens to sessions.list snapshots and, after the marker session is removed, triggers sessions.refresh() and sessions.refreshSubagents(parentId), updating the subagent count without requiring a manual page refresh.

HTTP Routes

In addition to model-callable tools, the plugin registers HTTP endpoints for easier client integration and local debugging.

  • GET /dsh-plugin-subagent-delete/list?parentSessionId=<id>[&activity=…][&mode=…]
  • POST /dsh-plugin-subagent-delete/delete { "parentSessionId": "<id>", "subagentId": "<id>", "recursive": false }
  • POST /dsh-plugin-subagent-delete/release { "parentSessionId": "<id>", "subagentId": "<id>", "recursive": false }

Access Control and Dependencies

Permission Rules

  • Ownership check: Only ancestors in the session tree are allowed to delete a subagent. Attempts to delete a non-descendant or an unknown ID return a not-your-subagent or not-found error.
  • Recursive deletion restriction: If recursive: true is not set, attempts to delete a subagent that has descendants are rejected.
  • Running wait: Running subagents wait for 15 seconds before deletion to ensure they are fully stopped.

Environment Dependencies

  • DeepSeek Harness: Compatible with DSH 0.1.0-rc.8
  • Node.js: Requires version ^22.19.0 or >=24.0.0
  • Dependencies: Depends on @deepseek-ai/dsh-tools, with version range >=0.1.0-rc.8 <0.2.0-0

Summary

dsh-plugin-subagent-delete provides DSH with full subagent lifecycle management capabilities, especially an effective solution for cleaning up sessions that accumulate in the Web UI. Developers can integrate it using the commands and examples above to keep the environment tidy in session management.