Introduction¶

Developers running long tasks on DeepSeek Harness (DSH) have likely encountered this state: The Agent is still running, tool calls are coming in one after another, but the todo list on the panel remains stuck from a few minutes ago—completed items still show as incomplete, new blockages aren’t recorded, and there’s no way to determine the next step. The longer the task, the less reliable this panel becomes.

Such problems were usually solved by simply reminding the model to “update in time” in the prompt, lacking mechanism-level constraints. dsh-todo-freshness-guard changes the approach: counting and reminding at the Harness layer, and directly blocking ordinary tool calls when necessary, until the model resubmits a complete todo list. Here is an introduction to this plugin.

What is this¶

dsh-todo-freshness-guard is an out-of-tree DeepSeek Harness Guard plugin maintained by lamost423, current version 0.1.1, package status is community preview. It solves only one problem: when the todo_write list has already expired, first remind the model to reconcile the complete list; if the reminder is ineffective, block ordinary tool calls.

Two boundaries need to be clarified in advance: it only fixes stale todo_write state, does not replace or patch the filesystem Write tool; the compatibility target is DeepSeek Harness 0.1.0-rc.6, Node.js version requirement is ^22.19.0 || >=24.0.0.

How it works¶

The plugin’s entire behavior revolves around a successful todo_write. When a todo_write is successfully submitted and the list contains uncompleted items, the plugin counts non-accounting tool calls per Session, then processes in two tiers:

1. When the count reaches reminderAfterCalls, inject a reminder visible to the model, requiring the model to reconcile the complete todo list;
2. After the count exceeds blockAfterCalls, reject ordinary tool calls until a new complete todo_write replaces the list.

Always reachable paths¶

Blocking is not a blanket approach; the following rules ensure the model always has a recovery method:

• todo_write is always reachable;
• The outer run_code invocation path remains reachable, and Code Mode can still call todo_write;
• Native calls and Code Mode SDK sub-calls share the same counter; switching paths won’t bypass or reset the counter;
• When all to-do items are completed or empty, force auto-stop.

Installation and Enablement¶

First, install the compatible DSH CLI, then add the release archive to the profile that needs to enable the guard (using web as an example), and finally start:

npm install --global @deepseek-ai/dsh@0.1.0-rc.6
dsh plugin --profile web add https://github.com/lamost423/dsh-todo-freshness-guard/releases/download/v0.1.1/dsh-todo-freshness-guard-0.1.1.tgz
dsh web

If you want to install from source checkout, use the following process:

git clone https://github.com/lamost423/dsh-todo-freshness-guard.git
cd dsh-todo-freshness-guard
corepack enable
pnpm install --frozen-lockfile
pnpm build
dsh plugin --profile web add .
dsh web

Default Configuration¶

The plugin’s built-in default patch layer is as follows:

- insert:
    - id: todo-freshness-guard
      name: dsh-todo-freshness-guard
      config:
        reminderAfterCalls: 5
        blockAfterCalls: 8

That is, by default, remind on the 5th call and block after the 8th. Both values have constraints: blockAfterCalls must be an integer greater than reminderAfterCalls, and both must be positive integers.

Also, pay attention to the loading order: profiles and command-line patch layers loaded after this bundle may replace this configuration. After adjusting the thresholds, it is recommended to run a round in practice to confirm the value that actually takes effect is the one you want.

Removal and Verification¶

Remove it with one command when not needed:

dsh plugin --profile web remove dsh-todo-freshness-guard

If you have modified the source code, the repository provides two verification commands: pnpm check runs type checking, tests, and building sequentially, pnpm pack --pack-destination /tmp packages it to the specified directory.

pnpm check
pnpm pack --pack-destination /tmp

Test coverage includes native and Code Mode strategies, concurrent reset, Loader combination, bundling and Bundle contract testing, and actual startup of Web via official DSH 0.1.0-rc.6.

Applicable Scenarios and Notes¶

The applicable scenarios are clear: users running long tasks on DSH 0.1.0-rc.6 who rely on the todo list to observe progress. If tasks are generally short and the model can always update the list in time, the footprint of this plugin will be very low.

There are a few points that must be noted before use:

1. The plugin runs with the permissions of the current dsh process; check the source code and license before installing. The license is MIT, and derivative parts retain the DeepSeek Harness license; see the NOTICE file in the repository for details;
2. The package status is community preview, the compatibility target is locked to DeepSeek Harness 0.1.0-rc.6, and compatibility needs to be reconfirmed after DSH upgrades;
3. It only handles stale todo_write states, issues with the filesystem Write tool are not within its scope;
4. The configuration may be replaced by subsequent loaded patch layers; after changing the thresholds, confirm the actual effective value.

Conclusion¶

A one-sentence summary: dsh-todo-freshness-guard turns “model self-initiated updates of todo” into a mechanism constraint at the Harness layer—first remind, then block, while preserving both todo_write and run_code paths, making the progress panel of long tasks reliable again.

• GitHub Repository: https://github.com/lamost423/dsh-todo-freshness-guard
• Community Directory Page: https://www.skillhub.cn/plugins/lamost423/dsh-todo-freshness-guard

It should be noted that this community directory is an independent site and has no official affiliation with DeepSeek or Huanfang; DSH’s philosophy is “everything is a plugin,” and such community guard plugins are precisely the daily components of this ecosystem.