Introduction¶

In DeepSeek Harness (DSH) development, managing extremely long tool results is a common pain point. DSH includes two built-in mechanisms: dsh-spill-policy and dsh-compaction-tool-result-pruner. The former triggers when a result exceeds 50KB, while the latter triggers when the text exceeds 8192 characters and compaction pressure conditions are met. The former supports lossless recovery, whereas the latter cannot recover intermediate content on the model side. The plugin introduced in this article fills that gap and aims to solve the pruning and recovery of intermediate tool results.

What Is This?¶

This is a dsh-plugin for DeepSeek Harness (DSH). Its core behavior is to preferentially spill oversized plain-text tool results to a file after tool execution, and then replace the original result with a head/tail preview containing exact truncation locations and a file locator. This ensures the model can always recover the truncated middle content using read, grep, or sed, with no data loss. It is maintained by may3rr and distributed under the MIT License.

Core Features¶

1. Lossless Pruning: Prunes DSH tool results without losing any data.
2. Spill Before Pruning: Writes oversized plain-text results to a file first, then keeps the head and tail in the content returned to the model.
3. Precise Location: The preview includes the exact elided range and the path to the spill file.
4. Recoverability: The model can use read, grep, or sed to retrieve truncated middle sections from the spill file.
5. Listener Mode: Runs as a tools/post-execute waterline listener and performs pruning after tool projection and other hooks.
6. Idempotency: Pruned content is always kept within the threshold, so it is not pruned repeatedly.

Installation and Enablement¶

Installation requires a single command:

dsh plugin --profile web add dsh-tool-result-guard

After installation, restart DSH. The plugin is automatically applied to all agent presets under the profile.

The configuration file is located at ~/.dsh/profiles/web/cordis.patch.yml:

- id: tool-result-guard
  config:
    thresholdChars: 16384

Typical Usage¶

Recovering pruned content
When the model receives a pruned result similar to the following:

[pruned: kept chars [0, 4096) + [28976, 30000) of 30000; the elided middle
[4096, 28976) is NOT lost — full output saved at: /tmp/dsh-spill/.../bash.txt.
Recover any elided span with the read tool (offset/limit), grep, or sed on that file.]

<head: first 4096 chars>
...
<tail: last 1024 chars>

The model can use the read tool (with offset/limit parameters), grep -n, or sed -n 'X,Yp' to read the truncated portion from the spill file.

Configuring the pruning threshold
Adjust the pruning parameters in the configuration file:

- id: tool-result-guard
  config:
    thresholdChars: 8192    # 超过此字数开始剪枝
    headChars: 4096          # 保留前多少字符
    tailChars: 1024          # 保留后多少字符
    excludeTools: ["read"]   # 不剪枝这些工具的结果

Applicable Scenarios and Cautions¶

Applicable scenarios
Suitable for scenarios that require handling medium-length tool results (8K-50K bytes) that exceed the handling range of dsh-compaction-tool-result-pruner but do not reach the threshold of dsh-spill-policy. It fits LLM Agent development that requires fully model-side control and zero data loss.

Notes
1. Configuration limits: headChars + tailChars must be less than thresholdChars; otherwise, the marker cannot be placed in the result.
2. Failure handling: If writing the spill file fails, the plugin keeps the original inline result unchanged (Fail-open) and does not cause an error in the task.
3. Configuration key validation: Unknown keys in the configuration file cause loading to fail, so only supported fields must be used.
4. Dependency requirement: Node.js runtime version >= 18 is required.
5. Permissions and security: The plugin runs with the permissions of the current DSH process. Review the source code and license before installation.

Brief Conclusion¶

With dsh-tool-result-guard, DSH developers can address the pain point of unrecoverable intermediate pruning of tool results. By combining file spilling and precise markers, it ensures the integrity of context management. See the plugin directory or source repository for more details.