dsh-subagent-bridge

Let Codex or Claude Code drive DeepSeek Harness sessions as subagents — and let DSH drive them back.

中文说明

The plugin runs inside the Harness host and exposes a loopback MCP endpoint. It uses public host services (sessionController, sessions, workspaceRegistry, userQuestions) — no credential files, no cookie forgery.

Highlights

• One tool call, one answer. dsh_task opens a session, delivers the message, blocks until the turn ends, and returns only the final assistant text.

• Parallel workers. dsh_spawn returns immediately; dsh_wait blocks until any of them settles.

• Per-call model and project. Pin a worker to provider/model and file it under a named workspace without touching profile defaults.

• Queue or steer. Choose whether a follow-up waits for the running turn or is inserted into it.

• Unattended by default. Workers are told to assume a reasonable default instead of stopping to ask.

• Reverse direction. codex_dispatch and claude_dispatch hand work to Codex or Claude Code, with resumable threads.

• Loop guard. Depth and rate limits stop the two agents from delegating to each other in circles.

Related MCP server: subagent-harness-mcp

Requirements

• DeepSeek Harness ^0.2.1-0.

• Codex CLI (codex) and/or Claude Code CLI (claude) on PATH for the reverse direction.

Install

git clone https://github.com/Dogtiti/dsh-subagent-bridge

Open Plugins → Add in DSH and pick that directory. On start the plugin listens on 127.0.0.1:47821 and writes the endpoint file:

{
  "url": "http://127.0.0.1:47821/mcp/<token>",
  "port": 47821,
  "token": "<token>",
  "pid": 12345,
  "startedAt": "2026-10-22T12:30:00.000Z"
}

~/.dsh/bridge/endpoint.json, directory 0700, file 0600.

Connect

Codex

codex mcp add dsh-bridge --url "$(node -p "require(process.env.HOME+'/.dsh/bridge/endpoint.json').url")"
codex mcp list                # verify
codex mcp remove dsh-bridge   # remove

The desktop app and the CLI share ~/.codex/config.toml, so both see it. The token lives in the URL path, so no environment variable is needed — the desktop app cannot receive custom ones when launched from Finder. Authorization: Bearer <token> works too.

Claude Code

claude mcp add --transport http dsh-bridge "<the url above>" --scope user

Usage

// Synchronous: wait for the turn, get the answer
dsh_task({ prompt: "Review the error handling in src/bridge.ts", cwd: "/repo" })

// Asynchronous: hand out work, then wait for all of it
dsh_spawn({ task_name: "audit_api", message: "…", cwd: "/repo" })
dsh_spawn({ task_name: "audit_ui",  message: "…", cwd: "/repo" })
dsh_wait({ targets: ["audit_api", "audit_ui"], timeoutMs: 240000 })

// Continue an existing worker
dsh_followup({ worker: "audit_api", message: "Expand item 3 and attach a patch" })

Tools

dsh_list_sessions never returns message content, and dsh_read_result only works for sessions this bridge has dispatched to.

Model

dsh_task({ prompt: "…", model: "zai-coding-cn/glm-5.3", reasoningEffort: "max" })
dsh_spawn({ task_name: "review", message: "…", model: "opencode-go/deepseek-v4.1-flash" })

• provider/model; a bare model id keeps the current default provider.

• reasoningEffort is optional and model-dependent.

• Omitted means the session is untouched.

• The switch happens before the first prompt, so the worker's first turn already runs on it, and the profile default model is not modified.

Workspace

DSH groups sessions into projects; a new session lands under "Ungrouped" unless its directory is already a project.

dsh_task({ prompt: "…", cwd: "/repo/clawer", workspace: true })    // create, titled after the directory
dsh_spawn({ task_name: "w1", message: "…", cwd: "/repo/clawer", workspace: "Clawer" })
dsh_task({ prompt: "…", cwd: "/repo/clawer" })                     // reuse only

Missing directories are created first (registration requires an existing directory). An existing project is reused without retitling. The result carries workspace: { id, title, path }. A failure here never fails the dispatch.

Queue or steer

DSH's "sending while busy" has exactly two behaviours:

dsh_followup({ worker: "w1", message: "Only touch files under src from here", mode: "steer" })

Two measured facts:

1. steer does not interrupt a running tool call. A worker inside sleep 90 only sees the message when that call returns (70s in our test). Stopping it is the UI's cancel action, not a delivery mode.

2. steer does not open a new turn — the turn number stays the same, so the bridge waits for the current turn to end. Waiting for the next one blocks until the timeout.

dsh_task refuses a running session unless mode: "steer" is given, and the error message says so. A steered reply shares the turn with the original task, so the bridge anchors the answer on its own user message rather than the turn's last assistant text.

Unattended workers

A worker that calls ask_user_question waits for a human. When the caller is another agent, nobody is there. So the bridge appends a standing instruction to every delegated task:

(If information is missing, or a choice between options is required, pick the most
 reasonable default, finish the task, and state the assumption in one line. Do not
 hand the decision back to the user and do not call ask_user_question.)

On by default (assumeDefaults: false disables it). It is skipped when the prompt already mentions ask_user_question.

Replace the wording with assumptionPolicy — Chinese, for instance:

config:
  assumptionPolicy: "如果缺少必要信息，直接采用最合理的默认做法做完，并在结果里用一行说明你的假设。"

Questions (pendingQuestion)

If a worker does ask, dsh_wait reports it:

{
  "status": { "w1": "running" },
  "pendingQuestion": {
    "callId": "call_abc",
    "questions": [{ "id": "mode", "question": "Which mode?", "options": [{ "label": "Fast" }] }]
  },
  "next": "blocked on a question: answer it with dsh_answer, or call dsh_wait again"
}

dsh_answer({ worker, answers: [{ id: "mode", selected: ["Fast"] }] }) submits a batch.

Known limit: DSH's userQuestions.answer() only accepts questions that have already timed out into the continued state. A question still blocking inside the tool call belongs to the web UI's answerer, and the bridge cannot answer it (answered: false in practice). Prefer assumeDefaults over waiting for a question.

Reverse direction

Both tools are registered for agents of this deployment.

codex_dispatch

Returns { ok, text, threadId, exitCode, durationMs }. Runs codex exec [resume <id>] --json -o <tmpfile>, reads thread.started from the event stream and the final message from the -o file. sandbox and cwd are ignored on resume — codex exec resume accepts neither.

claude_dispatch

Returns { ok, text, sessionId, durationMs }. Runs claude -p --output-format json and reads the single JSON object on stdout. stderr is advisory — the CLI warns about an unrecognised model suffix while still succeeding.

Configuration

- insert:
    - id: subagent-bridge
      name: 'dsh-subagent-bridge'
      config:
        port: 47821

A busy port is reported, not silently replaced: the endpoint file gets an error field and the host log prints subagent-bridge: could not start on port ….

Guardrails

Depth. Both agents can see the same bridge, so a circle is possible: DSH worker → codex_dispatch → that Codex run → dsh_spawn → … Each dispatch computes max(in-flight depth, caller depth) + 1 and refuses beyond maxHops:

codex_dispatch would create delegation depth 2, but maxHops is 1.
Carry the work out directly instead of delegating again.

Rate. dispatchPerMinute (default 10) catches bursts and tight retry loops:

rate limit: 10 dispatches per 60s reached; retry in 23s

Slots. 4 workers per cwd, 12 globally. A finished worker keeps its slot until dsh_close; records older than 24h stop counting. Blocking dsh_task calls are registered but do not consume a slot. Buckets are keyed by cwd because the MCP endpoint is shared and carries no session identity.

Persistence. workers.json keeps the registry and each turn's baseline: workers survive a restart, finished ones replay their cached answer, cold sessions report offline, and the file keeps at most 200 records.

Security. Loopback only; every request needs the token in the path or a bearer header, compared in constant time; the token is generated once and persisted. Holding the endpoint file is equivalent to being able to send messages to sessions — keep its 0600/0700 permissions. DSH's own sandbox and approval rules still apply to anything delivered.

How it works

Codex / any MCP client
  │  POST /mcp/<token>   JSON-RPC (stateless, single JSON response)
  ▼
dsh-subagent-bridge (inside the host process)
  · node:http on 127.0.0.1:47821
  · initialize / tools/list / tools/call / ping
  · sessionController.prompt({ sessionId, requestId, mode, content })
  · sessions.get(id).snapshotEvents() to read text back

The protocol is a stateless subset of streamable HTTP: each POST returns one application/json body and nothing is pushed, so results are collected by long polling. The server stops waiting the moment the client disconnects.

Skills

Two installable skills turn this into behaviour a model follows rather than a tool it might forget:

mkdir -p ~/.codex/skills && cp -R skills/deepseek-worker ~/.codex/skills/
mkdir -p ~/.dsh/skills  && cp -R skills/delegate-to-external-agent ~/.dsh/skills/

Both are plain SKILL.md files: YAML frontmatter (name + description) plus body. Triggering depends entirely on the description, so they carry bilingual trigger phrases and explicit "don't use" boundaries. Changes take effect without a restart.

Compatibility

• DSH ^0.2.1-0 (engines.dsh).

• MCP protocol versions 2025-06-18, 2025-03-26, 2024-11-05; unknown versions fall back to the newest.

• Requires the public services sessionController, sessions, workspaceRegistry, userQuestions. Missing ones surface as explicit tool errors.

Development

node --test "test/*.test.mjs"

index.js              wiring: apply() + re-exports
src/constants.js      versions, limits, binary candidates, policy text
src/utils.js          JSON-RPC helpers, argument validation, sleep
src/settings.js       defaults and config resolution
src/tools.js          tool schemas
src/policy.js         the standing instruction
src/questions.js      ask_user_question takeover and reporting
src/sessions.js       session reads, waits, model and workspace placement
src/guards.js         depth and rate limits
src/registry.js       worker registry persistence and capacity
src/http.js           loopback server, JSON-RPC, tool dispatch
src/api.js            the bridge API the tools call
src/runners/codex.js  codex exec adapter
src/runners/claude.js claude -p adapter

83 tests: handshake and version negotiation, tool list and argument validation, dispatch call shape, result baselines, long polling, real HTTP round trips (404/405/202 and bearer), codex exec event parsing, binary resolution, success/failure/timeout runs, resume argument split, final-answer-only behaviour, dsh_wait terminal states, slot limits and release, followup rebaselining, registry persistence and restart recovery, maxHops and rate limiting, per-cwd budgets, workspace creation and reuse, queue/steer delivery and waiting, anchors for steered answers, Claude output parsing and resume arguments, assumeDefaults injection, pendingQuestion and dsh_answer.

Related

License

MIT © Dogtiti