In DeepSeek Harness (DSH), when a background subagent fails midway (for example, due to model API 429 rate limiting), the core-generated notification usually discards the specific cause. It only shows a generic failure description, followed by blank content. The actual error is recorded in the subagent session’s terminal turn/end event, but it is not passed to the parent agent. This plugin listens for that event, reads the details from session storage, and routes the specific failure reason back to the parent agent.

Plugin Scope

  • Name: dsh-subagent-error-details
  • Type: DSH plugin
  • Maintainer: sijie-ni-0214
  • Core Value: When a background subagent fails, passes the specific failure reason (such as RATE_LIMIT 429) to the parent agent, instead of showing only a generic notification.

Core Features

  1. Event Listening: Listens for the public subagent/end event.
  2. Detail Parsing: When stopReason === "error", parses the terminal turn/end failure details of the subagent session via sessionPersistence.load().
  3. Routing Back: Uses the subagent session header’s parentSession and agent registry to route the real error details back to the parent agent that owns the subagent.
  4. Attached Message: Sends an attached message to the parent agent, displaying the specific error information (for example, RATE_LIMIT: 429 Rate limit exceeded).

Installation and Enablement

The plugin is installed via a package manager and mounted into the DSH configuration. After installation, DSH must be restarted for the changes to take effect.

Official Installation Command (applies to all agent presets):

dsh plugin --profile web add dsh-subagent-error-details

Local Development Installation (from a local path):

cd ~/.dsh/profiles/web
pnpm add file:/path/to/dsh-subagent-error-details

Typical Usage and Output

After installing and restarting DSH, when a background subagent fails due to rate limiting, the parent agent will receive an attached message containing the specific cause:

Subagent <id> failed with: RATE_LIMIT: 429 Rate limit exceeded for api_key ... Limit resets at ...

Use Cases and Caveats

  • Version Dependency: Requires dsh.engines.dsh: >=0.1.1-rc.2 <0.2.
  • Data Reading: Persistent reading depends on the session checkpoint policy having flushed the turn/end event.
  • Notification Text: The official notification text is generated by the core and remains unchanged; this plugin only adds an attached message.
  • One-Time Runs: One-time in-process runs without session records can only report stopReason and cannot retrieve details.
  • Dependencies: The plugin has zero runtime dependencies and only introduces type definitions as a development dependency.

Summary

This plugin resolves the issue of lost failure information for background subagents in DSH by listening to the event chain and reading from session persistent storage, then feeding the true error cause back to the parent agent. It currently depends on upstream DSH version 0.1.1-rc.2 or above.