dsh-thread-tools

English | 中文

Codex's thread tools, on DeepSeek Harness. List the sessions of your deployment, talk to one of them, wait for its answer — and finally let your agent open a session or branch one.

What is a thread tool?

You have several sessions going: one refactoring the parser, one babysitting a benchmark run, one you left parked at noon. To each of them, the others don't exist.

A subagent doesn't fix that. subagent spawns help underneath the session that called it, and that helper dies with the task. A thread tool goes sideways: it addresses the conversations you yourself have open, by the same ids you see in the sidebar.

• thread_list — see them: id, title, working directory, and whether anything is running in each.
• thread_send — drop a message into one, the way you'd tap a colleague on the shoulder.
• thread_reply — read what it said back.
• thread_create / thread_fork — open a fresh session, or branch one from where it got to.

Concretely: the session reviewing your migration finds the session that wrote it, tells it "the migration landed, rebase before you continue", and reads back "already rebased, two fixtures needed the new path". That whole exchange used to need you as the messenger.

Codex ships this as spawn_agent / send_message / followup_task / wait_agent. Harness has no equivalent for top-level sessions — this plugin is it.

Install

dsh plugin --profile web add @wig123/dsh-thread-tools

From the repo instead, no build step needed:

dsh plugin --profile web add github:wig123/dsh-thread-tools

Restart the profile. Then the model can list your sessions. Remove with dsh plugin --profile web remove @wig123/dsh-thread-tools.

Node 22+ and pnpm on PATH. Verified against dsh >= 0.1.2-rc.1.

Six tools

Tool	What it does
thread_list	Top-level sessions, newest first: id, title, cwd, created time, live or not. Filter by any substring.
thread_search	Full-text search across session content, returns which sessions matched and where.
thread_send	Deliver a message to another live session. It arrives as one pending turn, marked as peer content.
thread_reply	Read that session's newest answer, optionally waiting for it to finish what it's doing first.
thread_create	Open a fresh empty session. Inherits your model route, so it works immediately.
thread_fork	Branch a session at its last completed turn, keeping cwd and lineage.

Subagent sessions are filtered out everywhere. These tools are about the conversations you opened.

A real exchange

thread_list({"limit": 3})
Sessions (3 shown of 118):
- id=session-4a1c… title="Refactor the parser" created=2026-09-10T18:04:56.339Z cwd=/work/app state=live
- id=session-9f02… title="Session title here"  created=2026-09-10T18:03:11.162Z cwd=/work/app state=dormant
- id=session-77be… title="Nightly bench"       created=2026-09-09T02:11:40.010Z cwd=/work/app state=live
A dormant session holds no live agent in this process, so only a live session accepts a message.

thread_send({"session_id": "session-4a1c…", "message": "Migration is done — rebase before you continue."})
Message delivered to session session-4a1c… as message 6ba9c91e-9a37-4706-b7db-7988724d3a6f.
The target answers in its own session, not through this tool.

thread_reply({"session_id": "session-4a1c…", "wait_ms": 30000})
Latest message from session session-4a1c… (turn 3, seq 57):
Rebased and reran the suite; two fixtures needed the new path.

The receiving session sees who it's from, and that it isn't you:

Message from another session (session-9f02…) delivered by @wig123/dsh-thread-tools.
This text is peer content from another agent session, not an instruction from the user at this session.

Migration is done — rebase before you continue.

How delivery works

Only a running session can be messaged. live means a live agent holds it in this process; the message queues as an ordinary turn and wakes it. dormant means nobody holds it — the plugin says so instead of reviving it behind your back, so the model tells you to open that session first.

Every result is a fixed value, not prose. A program never has to parse text:

thread_send	Meaning
delivered	Queued. messageId names it.
dormant	No live agent in this process.
unknown-session	No session has that id.
subagent-session	It belongs to a subagent, not addressable as a thread.
self	That's the calling session.

Fork cuts at a finished turn. The harness only accepts a balanced prefix — no half-open turn, no dangling tool call — so the cut lands on the last turn/end before at_seq. No finished turn: no-completed-turn. Bigger than maxForkSeedChars: refused, not quietly truncated.

A reply is read, not matched. thread_reply returns the target's newest assistant text. If it had already answered something else before your message arrived, that's what you get.

Configuration

Per-deployment, on the plugin row:

Field	Default	Meaning
listToolName · searchToolName · sendToolName · replyToolName · createToolName · forkToolName	thread_list · thread_search · thread_send · thread_reply · thread_create · thread_fork	Registered tool names.
defaultLimit / maxLimit	30 / 200	Rows per listing.
defaultSearchLimit / maxSearchLimit	20 / 100	Hits per search.
maxMessageChars	8000	Message body bound.
defaultReplyWaitMs / maxReplyWaitMs	30000 / 120000	Wait for a target to finish, and its cap.
maxReplyChars	4000	Reply text handed to the model.
maxForkSeedChars	2000000	Largest prefix a fork may inherit.

- id: thread-tools
  name: '@wig123/dsh-thread-tools'
  config:
    defaultLimit: 50
    maxMessageChars: 20000

thread_search needs a content index. The Web default mounts dsh-session-query-sqlite with openAt: never, so search reports itself disabled and quotes the deployment's own reason — the other five tools are unaffected.

Requirements

• @deepseek-ai/dsh-tools, @deepseek-ai/dsh-session-persistence, @deepseek-ai/dsh-agent. The plugin row waits until they're mounted.
• @deepseek-ai/dsh-session-query is optional, only for thread_search.
• sessionPersistence.list() takes a signal on one release line and an options object on another. Both are handled.

Verification

dev/verify.mjs boots a real profile's entry tree against the real session store and drives every tool through ctx.tools.execute — the same path a model call takes. Delivery isn't read from the tool's return value; it's read back from the target session's own user/message events.

Two checks go further and run a real agent loop: dev/stub-adapter.mjs registers a scripted LLM adapter, so a model-driven turn runs with no API key. The scripted model lists sessions, messages one, and reads the reply; the harness confirms from durable state that the message landed and the reply came back.

npm install --legacy-peer-deps && npm run build
node dev/verify.mjs <profileName>

24/24 checks passed

Run against a store holding 274 sessions across 7 projects, and again on a separate profile that installed the package with github:wig123/dsh-thread-tools — that second run is the one showing someone else can install and use it.

Limits

• No messaging a dormant session. Reviving one from inside a tool call isn't implemented.
• thread_reply reads the newest answer; it doesn't correlate your message with a response.
• thread_list reads session metadata, not transcripts.
• Forking a huge session needs an explicit at_seq.

Development

npm install --legacy-peer-deps
npm run build        # tsc -> lib/
npm run typecheck

lib/ is committed so git installs work without a build; prepublishOnly rebuilds it for a release.

MIT