dsh-baton-mcp 0.5.6 → 0.5.8

package/README.md

@@ -88,14 +88,16 @@ That is all. If Harness says it could not register, run `npx -y dsh-baton-mcp se
 | `dsh_create_workspace` | Register a folder as a workspace (creates the folder if missing); returns the existing one if already registered |
 | `dsh_list_sessions` | Sessions newest first, with title, folder and running state; filter by folder or text. Archived sessions are left out |
 | `dsh_read_session` | Recent prompts and replies of one session (with tool names); `archived: true` for an archived session |
-| `dsh_send` | Send a message: `session_id` continues that session; `cwd` or `workspace_id` starts a new one (a `cwd` that is not a workspace yet is registered first). Returns a `run_id` at once. In Harness the message is marked "Sent by Claude / ChatGPT from another chat". An archived session is refused: unarchive it in Harness, or start a new session |
+| `dsh_send` | Send a message: `session_id` continues that session; `cwd` or `workspace_id` starts a new one (a `cwd` that is not a workspace yet is registered first). Returns a `run_id` at once. In Harness the message is marked "Sent by Claude / ChatGPT from another chat". An archived session is refused: unarchive it in Harness, or start a new session. To a busy session, `mode` `followup` queues the message after the current turn and `steer` adds it to the running turn; left out, it does what Harness's own setting says (Settings → sending while busy: queue or steer), and `followup` when that cannot be read. `mode_source` says which applied |
 | `dsh_status` | Run progress: state, recent text and tool calls, final reply; `waiting_on` when the turn is over but sub-agents or jobs still run; `human_interjections` when someone typed in the Harness UI mid-run; state `interrupted` for a run cut short by a Harness restart |
-| `dsh_wait` | Wait for the run to end: up to 270 s per call for Codex, 50 s for other clients. Still going: returns `timed_out` with just the state; call it again. Clients that can wait in the background use `dsh_send`'s `wait_command` instead. `dsh_status` is a one-off look, not a way to wait |
+| `dsh_wait` | Wait for the run to end (or until it stops to ask a person, see `dsh_answer`): up to 270 s per call for Codex, 50 s for other clients. Still going: returns `timed_out` with just the state; call it again. Clients that can wait in the background use `dsh_send`'s `wait_command` instead. `dsh_status` is a one-off look, not a way to wait |
+| `dsh_answer` | Answer the questions a run stopped to ask (Harness's ask_user_question): per question, an option number or label, free text, or skip; one at a time or all at once. `dsh_wait` and `wait_command` return as soon as a run asks, with the questions (`needs_input`, `question`, the recommended option marked). The assistant answers by its own judgment only when you told it to decide; otherwise it brings you the questions with its recommendation. You can also answer in the Harness window: whoever answers first wins |
 | `dsh_session_activity` | What a session is doing now: running turn, sub-agents (any depth), background jobs; `archived: true` for an archived session |
-| `dsh_cancel` | Stop everything a session is doing, by `run_id` or `session_id`: turn, sub-agents, jobs (queued messages stay) |
+| `dsh_update_queued` | Change a message still waiting in the queue of a busy session, by its `run_id`: `edit` its text, `remove` it, or `steer` it into the running turn now. Once it has reached the conversation it can no longer be changed |
+| `dsh_cancel` | Stop everything a session is doing, by `run_id` or `session_id`: turn, sub-agents, jobs. Harness also drops the messages waiting in its queue; their runs end as `cancelled` |
 | `dsh_rename_session` | Rename a session |
 | `dsh_rename_workspace` | Rename a workspace (sidebar title only; the folder is not moved) |
-| `dsh_list_runs` | Recent runs |
+| `dsh_list_runs` | Recent runs, optionally of one session |
 
 </details>
 

package/README.zh-CN.md

@@ -88,14 +88,16 @@ Codex 和 Claude 轮流往同一个 Harness 对话发消息，每条都标明是
 | `dsh_create_workspace` | 把一个文件夹登记为工作区（文件夹不存在会先创建）；已登记的直接返回原来那个 |
 | `dsh_list_sessions` | 列出对话（最新在前），带标题、目录、是否在跑；可按目录或关键字过滤。已归档的对话不会列出 |
 | `dsh_read_session` | 读某个对话最近的消息和回复（含用到的工具名）；已归档的对话会带 `archived: true` |
-| `dsh_send` | 发消息。带 `session_id` 续接那个对话；带 `cwd` 或 `workspace_id` 新开对话（`cwd` 还不是工作区时会先登记）。立即返回 `run_id`。Harness 里这条消息会标注「由 Claude / ChatGPT 从另一个聊天发送」。已归档的对话会被拒绝：先在 Harness 里取消归档，或新开对话 |
+| `dsh_send` | 发消息。带 `session_id` 续接那个对话；带 `cwd` 或 `workspace_id` 新开对话（`cwd` 还不是工作区时会先登记）。立即返回 `run_id`。Harness 里这条消息会标注「由 Claude / ChatGPT 从另一个聊天发送」。已归档的对话会被拒绝：先在 Harness 里取消归档，或新开对话。对话正忙时，`mode` 为 `followup` 会排在当前回合之后，`steer` 会插进正在跑的回合；不传时跟随 Harness 自己的设置（设置 → 繁忙时的发送行为：排队发送或插话发送），读不到设置时按 `followup`。返回里的 `mode_source` 说明用的是哪种 |
 | `dsh_status` | 查看运行进度：状态、最近的文字和工具调用、最终回复；回合结束但子智能体/后台任务还在跑时给出 `waiting_on`；中途有人在 Harness 界面里发消息时给出 `human_interjections`；被 Harness 重启打断的任务状态为 `interrupted` |
-| `dsh_wait` | 等运行结束：Codex 每次最多等 270 秒，其他客户端 50 秒。没做完会带 `timed_out`，只返回状态，再调用一次即可。能在后台等待的客户端改用 `dsh_send` 返回的 `wait_command`。`dsh_status` 只用来看一眼，不用来等待 |
+| `dsh_wait` | 等运行结束（或者等到它停下来问人，见 `dsh_answer`）：Codex 每次最多等 270 秒，其他客户端 50 秒。没做完会带 `timed_out`，只返回状态，再调用一次即可。能在后台等待的客户端改用 `dsh_send` 返回的 `wait_command`。`dsh_status` 只用来看一眼，不用来等待 |
+| `dsh_answer` | 回答运行中途提出的问题（Harness 的 ask_user_question）：每道题可以填选项编号或选项文字、自由填写，或者跳过；可以逐题回答，也可以一次答完。运行一提问，`dsh_wait` 和 `wait_command` 就会立刻返回，并带上题目（`needs_input`、`question`，推荐选项会标出来）。只有你说过让它自己决定时，助手才会按自己的判断回答；否则它会把题目和它的建议转给你。你也可以直接在 Harness 窗口里回答，谁先答就算谁的 |
 | `dsh_session_activity` | 对话此刻在做什么：正在跑的回合、子智能体（任意层级）、后台任务；已归档的对话会带 `archived: true` |
-| `dsh_cancel` | 按 `run_id` 或 `session_id` 停掉整个对话的工作：当前回合、子智能体、后台任务（排队中的消息不会被删） |
+| `dsh_update_queued` | 按 `run_id` 修改还在忙碌对话队列里等待的消息：`edit` 改文字，`remove` 撤回，`steer` 立刻插进正在跑的回合。消息一旦进入对话就改不了了 |
+| `dsh_cancel` | 按 `run_id` 或 `session_id` 停掉整个对话的工作：当前回合、子智能体、后台任务。Harness 会同时清掉队列里等待的消息，这些运行记为 `cancelled` |
 | `dsh_rename_session` | 给对话改名 |
 | `dsh_rename_workspace` | 给工作区改名（只改侧边栏标题，不动文件夹） |
-| `dsh_list_runs` | 列出最近的运行 |
+| `dsh_list_runs` | 列出最近的运行，可按会话筛选 |
 
 </details>
 

package/host/README.md

@@ -1,11 +1,31 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JialaoLiu/dsh-baton/main/assets/readme/hero.gif" width="100%" alt="dsh-baton: pass the baton from Claude Code or Codex to DeepSeek Harness, watch it run live, and get it handed back when it's done">
+</p>
+
+<p align="center">
+  <a href="https://github.com/JialaoLiu/dsh-baton#readme">dsh-baton</a> · <a href="https://github.com/JialaoLiu/dsh-baton/blob/main/README.zh-CN.md">中文说明</a>
+</p>
+
+<p align="center">
+  macOS · Windows (<a href="https://github.com/JialaoLiu/dsh-baton/blob/main/WINDOWS.md">guide</a>) · no Node.js needed · zero dependencies · MIT
+</p>
+
 # dsh-baton-host
 
-DeepSeek Harness plugin for [dsh-baton](https://github.com/JialaoLiu/dsh-baton#readme). It runs inside the Harness host (desktop app or `dsh web`) and serves a local, owner-only Unix socket (`~/.dsh-baton/host.sock`; a per-user named pipe on Windows, see [WINDOWS.md](https://github.com/JialaoLiu/dsh-baton/blob/main/WINDOWS.md)). Through it, an MCP client can list and create workspaces, create sessions, continue a specific session, and wait for its turn to finish. All of this goes through Harness's own session controller, so the messages show up live in the Harness UI.
+The DeepSeek Harness plugin for [dsh-baton](https://github.com/JialaoLiu/dsh-baton#readme). It runs inside the Harness host (desktop app or `dsh web`) and serves a local, owner-only Unix socket (`~/.dsh-baton/host.sock`; a per-user named pipe on Windows). Through it, an MCP client can list and create workspaces, create sessions, continue a specific session, and wait for its turn to finish. All of this goes through Harness's own session controller, so the messages show up live in the Harness UI.
 
 DeepSeek Harness 插件，配合 [dsh-baton](https://github.com/JialaoLiu/dsh-baton/blob/main/README.zh-CN.md) 使用。它运行在 Harness 内部，只开一个当前用户才能访问的本地套接字，让 MCP 客户端能新建工作区和对话、续接指定对话、等待任务完成。所有操作都走 Harness 官方会话服务，界面实时可见。
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JialaoLiu/dsh-baton/main/assets/readme/features.svg" width="100%" alt="Create workspaces and sessions, continue a session, run live in the Harness UI labelled with the sender, get woken when it is done, no extra API key, macOS and Windows with zero dependencies">
+</p>
+
 ## Install / 安装
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JialaoLiu/dsh-baton/main/assets/readme/install.svg" width="100%" alt="Step 1: in Harness open Plugins, Add plugin, enter dsh-baton-host, Install, Enable now; it registers dsh-baton for Claude Code and Codex. Step 2: in a new chat, ask for dsh_list_workspaces">
+</p>
+
 Harness → Plugins / 插件 → Add plugin / 添加插件 → `dsh-baton-host` → Install / 安装 → Enable now / 立即启用
 
 That is the whole install: switched on, the plugin registers the dsh-baton MCP server (the `dsh-baton-mcp` package, installed with it) for Claude Code and Codex, user-wide, and Harness says so. New conversations then have the `dsh_*` tools. If it could not register, run `npx -y dsh-baton-mcp setup`. Details: [dsh-baton](https://github.com/JialaoLiu/dsh-baton#install-details).
@@ -16,6 +36,12 @@ Update / 更新: uninstall, then add it again; the MCP server is updated with it
 
 Remove / 卸载: uninstall, then `npx -y dsh-baton-mcp setup --remove` / 卸载插件后运行 `npx -y dsh-baton-mcp setup --remove`.
 
+## How it works / 工作原理
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/JialaoLiu/dsh-baton/main/assets/readme/architecture.svg" width="100%" alt="MCP clients call dsh-baton-mcp over stdio; it reaches the dsh-baton-host plugin inside Harness through an owner-only local socket; the plugin drives Harness sessions live, with dsh headless as fallback">
+</p>
+
 ## Socket protocol / 套接字协议
 
 Newline-delimited JSON: request `{"id", "method", "params"}`, reply `{"id", "result"}` or `{"id", "error"}`.
@@ -27,14 +53,16 @@ Newline-delimited JSON: request `{"id", "method", "params"}`, reply `{"id", "res
 | `create_workspace` | `path`, `title?`, `create_dir?` (default `true`) |
 | `list_sessions` | `cwd?`, `query?`, `limit?` |
 | `read_session` | `session_id`, `last?` |
-| `send` | `message`, and `session_id` or `cwd` or `workspace_id`; `mode?` (`followup` \| `steer`) |
+| `send` | `message`, and `session_id` or `cwd` or `workspace_id`; `mode?` (`followup` \| `steer`; left out, Harness's busy-send setting, else `followup`) |
 | `status` | `run_id`, `tail?` |
 | `wait` | `run_id`, `timeout_s?` |
 | `activity` | `session_id` |
 | `cancel` | `run_id` or `session_id` |
 | `rename_session` | `session_id`, `title` |
 | `rename_workspace` | `workspace_id` or `path`, `title` |
-| `list_runs` | `limit?` |
+| `list_runs` | `session_id?`, `limit?` |
+| `answer` | `run_id`, `answers` (`[{ id?, choose?, text?, skip? }]`) |
+| `update_queued` | `run_id`, `action` (`edit` \| `remove` \| `steer`), `message?` (for `edit`) |
 
 `DSH_BATON_SOCKET` / `DSH_BATON_HOME` in the Harness process environment move the socket. `DSH_BATON_AUTO_REGISTER=0` turns off the MCP registration.
 

package/host/lib/index.js

@@ -122,9 +122,18 @@ export function apply(ctx) {
     try { ctx.logger?.error?.(`dsh-baton-host ${label}: ${error?.stack ?? error}`) } catch { /* logging must never throw */ }
   }
 
+  // A waterfall listener must never break Harness's chain: on any error of its own it
+  // hands the request on untouched.
+  const guardWaterfall = (fn) => function (request, next) {
+    try { return fn(request, next) } catch (error) { logError('waterfall', error); return next() }
+  }
+
   const controller = ctx.sessionController
   const registry = ctx.workspaceRegistry
+  // Harness's settings service, when this Harness has one: read for its busy-send setting.
+  let settings = null
   const runs = new Map() // runId -> run
+  let stopping = false // set when the plugin unloads: release every wait()
   const waiters = new Map() // runId -> Set<resolve>
 
   // --- run bookkeeping ------------------------------------------------------
@@ -136,12 +145,27 @@ export function apply(ctx) {
     ...(run.waitingOn ? { waiting_on: run.waitingOn } : {}),
     ...(run.supersededBy ? { superseded_by: run.supersededBy } : {}),
     ...(run.humanInputs?.length ? { human_interjections: run.humanInputs } : {}),
+    ...(run.question ? { question: run.question } : {}),
     ...(tail ? { recent_events: run.events.slice(-tail) } : {}),
   })
 
   const ACTIVE = ['queued', 'running', 'waiting']
   const isActive = (run) => ACTIVE.includes(run.state)
 
+  // Release callers blocked in wait() without ending the run (it needs a person now).
+  function wake(run) {
+    for (const resolve of [...(waiters.get(run.id) ?? [])]) resolve()
+  }
+
+  // The run now waits for a person. The next wait() returns at once with what is asked
+  // (once per episode: a second wait() blocks again until the run moves on).
+  function needsPerson(run, delayMs = 0) {
+    Object.assign(run, { state: 'waiting', waitNoticed: false })
+    persist(run)
+    if (delayMs) setTimeout(guard('waiting', () => wake(run)), delayMs)
+    else wake(run)
+  }
+
   function settle(run, state, extra = {}) {
     if (!isActive(run)) return
     Object.assign(run, extra, { state, endedAt: new Date().toISOString() })
@@ -250,9 +274,24 @@ export function apply(ctx) {
     // Turn state is kept only for a turn in progress and dropped at its end.
     if (event.type === 'turn/start') turns.set(session.id, { hasOutput: false })
     else if (event.type === 'assistant/message' && turns.has(session.id)) turns.get(session.id).hasOutput = true
+    // A run settled as removed from the queue whose message reaches the conversation
+    // after all (the removal check guessed wrong) is taken up again.
+    if (event.type === 'user/message') {
+      const lost = [...runs.values()].find((r) => r.removedFromQueue && r.state === 'cancelled' && r.sessionId === session.id && r.requestId === data.source?.rpcId)
+      if (lost) {
+        Object.assign(lost, { state: 'queued', removedFromQueue: false, error: null, endedAt: null })
+        pushEvent(lost, { type: 'queue_delivered' })
+      }
+    }
     const active = activeRunsFor(session.id)
     if (event.type === 'turn/end' && !active.some((r) => r.sawPrompt)) turns.delete(session.id)
     if (!active.length) return
+    // Something left Harness's queue: a queued run may have been removed (session stopped,
+    // or Remove in the Harness UI) rather than started. Checked once the dust settles.
+    if (event.type === 'agent/inbox/spliced' && data.removedCount > 0 && active.some((r) => !r.sawPrompt)) {
+      scheduleQueueCheck(session.id)
+      return
+    }
     if (event.type === 'user/message') {
       const run = active.find((r) => r.requestId === data.source?.rpcId)
       const opensTurn = !turns.get(session.id)?.hasOutput
@@ -388,7 +427,9 @@ export function apply(ctx) {
     if (status === 'running' && receivers.length) lastRunningAt.set(agent.id, Date.now())
     for (const run of outputReceiversFor(agent.id)) {
       if (status === 'running') run.state = 'running'
-      else if (status === 'waiting') run.state = 'waiting' // needs a person in the Harness UI (approval / question)
+      // Needs a person: a question (see user-questions/request) or an approval in the
+      // Harness UI. Waiters wake a moment later, so a question that comes with it is on the run.
+      else if (status === 'waiting') { if (run.state !== 'waiting') needsPerson(run, 500) }
       else if (status === 'error') settle(run, 'failed')
       else if (status === 'idle') run.idleSeen = true
     }
@@ -399,6 +440,208 @@ export function apply(ctx) {
     for (const run of agent ? outputReceiversFor(agent.id) : []) run.error = String(error?.message ?? error)
   }))
 
+  // --- Harness's queue (inbox) ------------------------------------------------
+  // A followup sent while the session is busy waits in Harness's inbox until the turn
+  // ends. Each pending message carries the request id it was sent with (source.rpcId),
+  // so a run finds its own message there.
+
+  const QUEUE_UNSUPPORTED = 'This DeepSeek Harness version cannot change queued messages: its session controller has no projections/updateQueue.'
+  const queueTimers = new Map() // sessionId -> timeout
+  const QUEUE_RECHECK_MS = Number(process.env.DSH_BATON_QUEUE_RECHECK_MS) || 2000
+
+  // Messages still pending in a session's inbox, or null when this Harness cannot say.
+  async function pendingMessages(sessionId) {
+    if (typeof controller.projections !== 'function') return null
+    const baseline = await controller.projections({ sessionId }, signal())
+    if (baseline === null) return [] // no such session: nothing is pending
+    const inbox = baseline?.values?.inbox
+    if (!inbox) return null
+    return [...(inbox['next-turn'] ?? []), ...(inbox['next-step'] ?? [])]
+  }
+
+  // Settle the runs whose message left the inbox without reaching the conversation:
+  // Harness drops the queue when a session is stopped, and the Harness UI can remove one.
+  // A message taken into the conversation also leaves the inbox, and its user/message
+  // event can trail behind (edited messages, a busy disk), so a run counts as removed
+  // only when it is still missing from both the inbox and the log a moment later.
+  async function reconcileQueue(sessionId) {
+    let gone = await missingFromQueue(sessionId, activeRunsFor(sessionId).filter((r) => r.admitted && !r.sawPrompt))
+    if (!gone.length) return []
+    await new Promise((resolve) => setTimeout(resolve, QUEUE_RECHECK_MS))
+    gone = await missingFromQueue(sessionId, gone.filter((r) => isActive(r) && !r.sawPrompt))
+    for (const run of gone) settle(run, 'cancelled', { error: 'Removed from the Harness queue before it ran.', removedFromQueue: true })
+    return gone.map((r) => r.id)
+  }
+
+  // Of these runs, the ones whose message is neither pending in the inbox nor in the
+  // session log. Nothing is missing when either cannot be read.
+  async function missingFromQueue(sessionId, waiting) {
+    if (!waiting.length) return []
+    const pending = await pendingMessages(sessionId)
+    if (pending === null) return []
+    const ids = new Set(pending.map((m) => m?.source?.rpcId))
+    const gone = waiting.filter((r) => !ids.has(r.requestId))
+    if (!gone.length) return []
+    const log = await controller.inspect(sessionId, signal()).catch(() => null)
+    if (!Array.isArray(log?.events)) return []
+    const delivered = new Set(log.events.filter((e) => e.type === 'user/message').map((e) => e.data?.source?.rpcId))
+    return gone.filter((r) => !delivered.has(r.requestId) && !r.sawPrompt)
+  }
+
+  function scheduleQueueCheck(sessionId) {
+    clearTimeout(queueTimers.get(sessionId))
+    queueTimers.set(sessionId, setTimeout(guard('queue check', () => { queueTimers.delete(sessionId); return reconcileQueue(sessionId) }), 1500))
+  }
+
+  ctx.effect(() => () => { for (const t of queueTimers.values()) clearTimeout(t) }, 'dsh-baton-host queue timers')
+
+  // Change a relayed message that is still waiting in Harness's queue: edit its text,
+  // remove it, or move it into the running turn as a steer.
+  async function updateQueued({ run_id, action, message }) {
+    if (!['edit', 'remove', 'steer'].includes(action)) throw new Error('action must be edit, remove or steer')
+    if (action === 'edit' && !message?.trim()) throw new Error('edit needs a non-empty message')
+    const run = getRun(run_id)
+    if (!isActive(run)) throw new Error(`Run ${run.id} is ${run.state}; only a queued run can be changed.`)
+    if (run.sawPrompt) throw new Error(`Run ${run.id} has already reached the conversation and can no longer be changed. Send a correction with dsh_send mode steer, or stop the session with dsh_cancel.`)
+    if (typeof controller.updateQueue !== 'function') throw new Error(QUEUE_UNSUPPORTED)
+    const pending = await pendingMessages(run.sessionId)
+    if (pending === null) throw new Error(QUEUE_UNSUPPORTED)
+    const item = pending.find((m) => m?.source?.rpcId === run.requestId)
+    const gone = `Run ${run.id} is no longer in the Harness queue: it has just started, or it was removed.`
+    if (!item) throw new Error(gone)
+    const change = action === 'edit' ? { kind: 'edit', content: [{ type: 'text', text: message }] } : { kind: action }
+    try {
+      await controller.updateQueue({ sessionId: run.sessionId, itemId: item.id, action: change })
+    } catch (error) {
+      if (error?.code === 'session/queue-item-not-found') throw new Error(gone)
+      if (error?.code === 'session/steer-unavailable') throw new Error(`The current turn of ${run.sessionId} no longer takes steering; the message stays queued.`)
+      throw error
+    }
+    if (action === 'edit') {
+      run.preview = message.slice(0, 200)
+      pushEvent(run, { type: 'queue_edit', text: message.slice(0, 500) })
+    } else if (action === 'steer') {
+      run.mode = 'steer'
+      pushEvent(run, { type: 'queue_steer' })
+    } else {
+      pushEvent(run, { type: 'queue_remove' })
+      settle(run, 'cancelled', { error: null })
+    }
+    return { ...publicRun(run, 0), action }
+  }
+
+  // --- questions (ask_user_question) ----------------------------------------
+  // Harness asks the user through the user-questions/request waterfall, whose answerer
+  // is the Harness UI. Listening first, the plugin puts the question on the runs of that
+  // turn (so wait() returns with it) and lets either side answer: the Harness UI, or
+  // dsh_answer through answerQuestion(). The first answer wins.
+
+  const questions = new Map() // sessionId -> open question
+  const RECOMMENDED = /\(recommended\)|（推荐）|\(推荐\)|推荐/i
+
+  function publicQuestion(entry) {
+    return {
+      question_id: entry.id,
+      count: entry.items.length,
+      questions: entry.items.map((q) => ({
+        id: q.id,
+        ...(q.header ? { header: q.header } : {}),
+        question: q.question,
+        ...(q.detail ? { detail: q.detail } : {}),
+        multi_select: !!q.multiSelect,
+        options: (q.options ?? []).map((o, i) => ({ number: i + 1, label: o.label, ...(o.description ? { description: o.description } : {}), ...(RECOMMENDED.test(o.label) ? { recommended: true } : {}) })),
+        free_text: true,
+        ...(entry.answers.has(q.id) ? { answered: true } : {}),
+      })),
+    }
+  }
+
+  function onQuestion(request, next) {
+    const sessionId = request?.agent?.id
+    const asked = sessionId && Array.isArray(request.questions) ? outputReceiversFor(sessionId) : []
+    if (!asked.length) return next()
+    const entry = { id: `q-${crypto.randomBytes(4).toString('hex')}`, sessionId, items: request.questions, answers: new Map(), runs: asked }
+    const ours = new Promise((resolve) => { entry.resolve = resolve })
+    questions.set(sessionId, entry)
+    for (const run of asked) {
+      run.question = publicQuestion(entry)
+      pushEvent(run, { type: 'question', question_id: entry.id, count: entry.items.length })
+      needsPerson(run)
+    }
+    // The Harness UI (next) gets its own signal: once dsh_answer wins, aborting it tells
+    // the window to drop its question card, which it otherwise keeps open.
+    const ui = new AbortController()
+    const harnessSignal = request.signal
+    request.signal = harnessSignal ? AbortSignal.any([harnessSignal, ui.signal]) : ui.signal
+    // With no Harness window to answer, only dsh_answer can: that is not a failure here.
+    const theirs = Promise.resolve().then(next).catch((error) => (error?.code === 'NO_PROVIDER' || ui.signal.aborted ? new Promise(() => {}) : Promise.reject(error)))
+    const aborted = new Promise((_, reject) => harnessSignal?.addEventListener('abort', () => reject(harnessSignal.reason), { once: true }))
+    const answered = (by) => (value) => {
+      for (const run of asked) pushEvent(run, { type: 'question_answered', question_id: entry.id, by })
+      return value
+    }
+    const fromBaton = ours.then((value) => { ui.abort(new Error('answered through dsh-baton')); return value })
+    return Promise.race([theirs.then(answered('harness')), fromBaton.then(answered('dsh-baton')), aborted]).finally(() => {
+      if (questions.get(sessionId) === entry) questions.delete(sessionId)
+      for (const run of asked) {
+        if (run.question?.question_id !== entry.id) continue
+        delete run.question
+        if (run.state === 'waiting') run.state = 'running'
+        persist(run)
+      }
+    })
+  }
+
+  // Answer the open question of a run's turn. answers: [{ id?, choose?: [number | label],
+  // text?, skip? }]; questions not answered yet stay open until every one has an answer.
+  function answerQuestion({ run_id, answers }) {
+    const run = getRun(run_id)
+    const entry = questions.get(run.sessionId)
+    if (!isActive(run) || !entry || run.question?.question_id !== entry.id) {
+      if (run.state === 'waiting') throw new Error(`Run ${run.id} is waiting for something in the Harness UI (an approval, for example) that cannot be answered from here; tell the user.`)
+      throw new Error(`Run ${run.id} is ${run.state} and has no open question to answer.`)
+    }
+    if (!Array.isArray(answers) || !answers.length) throw new Error('answers must list at least one answer')
+    const staged = new Map()
+    for (const a of answers) {
+      const q = a?.id != null ? entry.items.find((item) => item.id === a.id) : entry.items.length === 1 ? entry.items[0] : undefined
+      if (!q) throw new Error(a?.id != null ? `No question ${a.id}; the questions are ${entry.items.map((i) => i.id).join(', ')}` : 'id is required when there are several questions')
+      const options = q.options ?? []
+      const chosen = (a.choose ?? []).map((c) => {
+        const byNumber = typeof c === 'number' || /^\d+$/.test(String(c)) ? options[Number(c) - 1] : undefined
+        const option = byNumber ?? options.find((o) => o.label === c) ?? options.find((o) => o.label.toLowerCase().replace(RECOMMENDED, '').trim() === String(c).toLowerCase().replace(RECOMMENDED, '').trim())
+        if (!option) throw new Error(`Question ${q.id} has no option ${JSON.stringify(c)}; options: ${options.map((o, i) => `${i + 1}. ${o.label}`).join('; ')}`)
+        return option.label
+      })
+      const text = typeof a.text === 'string' && a.text.trim() ? a.text : undefined
+      if (a.skip && (chosen.length || text)) throw new Error(`Question ${q.id}: skip cannot come with choose or text`)
+      if (!a.skip && !chosen.length && !text) throw new Error(`Question ${q.id}: give choose, text or skip`)
+      if (!q.multiSelect && chosen.length > 1) throw new Error(`Question ${q.id} takes one option`)
+      // Single choice: typed text replaces the option (Harness's own rule).
+      staged.set(q.id, a.skip ? { id: q.id, selected: [] } : !q.multiSelect && text ? { id: q.id, selected: [], custom: text } : { id: q.id, selected: chosen, ...(text ? { custom: text } : {}) })
+    }
+    for (const [id, item] of staged) entry.answers.set(id, item)
+    const remaining = entry.items.filter((q) => !entry.answers.has(q.id)).map((q) => q.id)
+    if (remaining.length) {
+      for (const r of entry.runs) { if (r.question?.question_id === entry.id) { r.question = publicQuestion(entry); persist(r) } }
+      return { ...publicRun(run, 0), submitted: false, remaining }
+    }
+    entry.resolve({ answers: entry.items.map((q) => entry.answers.get(q.id)) })
+    return { ...publicRun(run, 0), submitted: true, answers: entry.items.map((q) => entry.answers.get(q.id)) }
+  }
+
+  ctx.on('user-questions/request', guardWaterfall(onQuestion), { global: true, prepend: true })
+
+  // Harness's own "busy send" setting (Settings → sending while busy: queue or steer),
+  // as a dsh-baton mode, or null when this Harness has no such setting to read.
+  function harnessBusyMode() {
+    try {
+      const form = settings?.describe?.()?.find?.((d) => d.ns === 'ui-conversation')
+      const value = form?.value?.busyEnter
+      return value === 'steer' ? 'steer' : value === 'queue' ? 'followup' : null
+    } catch { return null }
+  }
+
   // --- operations -----------------------------------------------------------
 
   const signal = () => new AbortController().signal
@@ -461,8 +704,13 @@ export function apply(ctx) {
     return { session_id, ...(isArchived(session_id) ? { archived: true } : {}), cwd: meta?.cwd ?? null, title, total_messages: messages.length, messages: messages.slice(-last) }
   }
 
-  async function send({ message, session_id, cwd, workspace_id, mode = 'followup', sender }) {
+  async function send({ message, session_id, cwd, workspace_id, mode: asked, sender }) {
     if (!message || !message.trim()) throw new Error('message is required')
+    if (asked != null && asked !== 'followup' && asked !== 'steer') throw new Error('mode must be followup or steer')
+    // Without a mode, a message to a busy session does what Harness's own busy-send setting says.
+    const fromHarness = asked == null ? harnessBusyMode() : null
+    const mode = asked ?? fromHarness ?? 'followup'
+    const modeSource = asked != null ? 'explicit' : fromHarness ? 'harness' : 'default'
     if (sender != null && !SENDER_RE.test(sender)) throw new Error('sender must be 1-32 characters of a-z, 0-9 or -')
     let sessionId = session_id
     let workspace = null
@@ -486,12 +734,14 @@ export function apply(ctx) {
     remember(run)
     try {
       await controller.prompt({ sessionId, requestId: run.requestId, content: [{ type: 'text', text: message }], mode }, signal())
+      run.admitted = true // in Harness's queue (or conversation) now
     } catch (error) {
       settle(run, 'failed', { error: String(error?.message ?? error) })
     }
     return {
       ...publicRun(run),
       mode,
+      mode_source: modeSource,
       ...(ahead.length ? { other_active_runs: ahead } : {}),
       ...(workspace ? { workspace } : {}),
     }
@@ -516,7 +766,10 @@ export function apply(ctx) {
   async function wait({ run_id, timeout_s = 300 }) {
     const run = getRun(run_id)
     const seconds = Number.isFinite(Number(timeout_s)) ? Math.min(Math.max(Number(timeout_s), 0), MAX_WAIT_S) : 300
-    if (isActive(run)) {
+    const unseenWait = () => run.state === 'waiting' && !run.waitNoticed
+    const deadline = Date.now() + seconds * 1000
+    // A wake can also come for another reason (the delayed one for a waiting status): wait on.
+    while (isActive(run) && !unseenWait() && !stopping && Date.now() < deadline) {
       await new Promise((resolve) => {
         const set = waiters.get(run.id) ?? new Set()
         waiters.set(run.id, set)
@@ -525,11 +778,15 @@ export function apply(ctx) {
           set.delete(done)
           resolve()
         }
-        const timer = setTimeout(done, seconds * 1000)
+        const timer = setTimeout(done, deadline - Date.now())
         set.add(done)
       })
     }
     const done = !isActive(run)
+    if (!done && unseenWait()) {
+      run.waitNoticed = true
+      return { ...publicRun(run), needs_input: run.question ? 'answer' : 'harness-ui' }
+    }
     return { ...publicRun(run), ...(done ? {} : { timed_out: true }) }
   }
 
@@ -568,6 +825,8 @@ export function apply(ctx) {
       } while (still.busy && Date.now() < deadline)
       if (!still.busy) break
     }
+    // Stopping a session also empties Harness's queue: the runs waiting there are over.
+    const removed = await reconcileQueue(sessionId).catch((error) => { logError('queue check', error); return [] })
     // The named run never reached the conversation (still queued, or sent to a session
     // that will not run it): settle it too, so nothing waits on it forever.
     if (run && isActive(run) && !run.sawPrompt) settle(run, 'cancelled')
@@ -578,6 +837,7 @@ export function apply(ctx) {
       still_busy: still.busy,
       activity: still.activity,
       queued_runs: activeRunsFor(sessionId).filter((r) => !r.sawPrompt).map((r) => r.id),
+      ...(removed.length ? { removed_from_queue: removed } : {}),
     }
   }
 
@@ -608,7 +868,9 @@ export function apply(ctx) {
     activity,
     rename_session: renameSession,
     rename_workspace: renameWorkspace,
-    list_runs: ({ limit = 10 } = {}) => [...runs.values()].reverse().slice(0, limit).map((r) => publicRun(r, 0)),
+    list_runs: ({ limit = 10, session_id } = {}) => [...runs.values()].reverse().filter((r) => !session_id || r.sessionId === session_id).slice(0, limit).map((r) => publicRun(r, 0)),
+    update_queued: updateQueued,
+    answer: answerQuestion,
   }
 
   // --- local socket (owner-only) ---------------------------------------------
@@ -675,6 +937,10 @@ export function apply(ctx) {
     registration = { state: 'off' }
   }
   if (typeof ctx.inject === 'function') {
+    ctx.inject(['settings'], (child) => {
+      settings = child.settings
+      child.effect(() => () => { if (settings === child.settings) settings = null }, 'dsh-baton-host settings')
+    })
     ctx.inject(['webServer'], (web) => {
       web.effect(() => web.webServer.register({
         kind: 'exact',
@@ -706,6 +972,7 @@ export function apply(ctx) {
       disposed = true
       if (store.enabled) { try { flushRuns() } catch (error) { logError('persist runs', error) } }
       store.enabled = false
+      stopping = true
       // Release callers blocked in wait() and close open connections, so an
       // unloaded or reloaded plugin leaves no timers or sockets behind.
       for (const set of waiters.values()) for (const done of [...set]) done()

package/host/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-baton-host",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "DeepSeek Harness plugin for dsh-baton: adding it is the whole install. Switched on, it registers the dsh-baton MCP server for Claude Code and Codex, then takes the baton over a local, owner-only control socket, runs it in a specific session through the host's own session controller, and hands the result back when the turn is done.",
   "type": "module",
   "main": "lib/index.js",
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "dsh-baton-mcp": "0.5.6"
+    "dsh-baton-mcp": "0.5.8"
   },
   "license": "MIT",
   "dsh": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-baton-mcp",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "mcpName": "io.github.JialaoLiu/dsh-baton",
   "description": "Pass the baton from Claude Code, Codex or any MCP client to a local DeepSeek Harness: an MCP server that hands off tasks, continues a specific session, shows the run live in Harness and hands the result back when it is done.",
   "type": "module",

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/JialaoLiu/dsh-baton",
     "source": "github"
   },
-  "version": "0.5.6",
+  "version": "0.5.8",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "dsh-baton-mcp",
-      "version": "0.5.6",
+      "version": "0.5.8",
       "transport": {
         "type": "stdio"
       }

package/src/cli.mjs

@@ -14,12 +14,14 @@ const USAGE = `Usage: dsh-baton <command> [args]
   read <session_id> [--last <n>]                          show recent messages
   send [--session <id> | --cwd <dir> | --workspace <id>] [--mode followup|steer] <message...>  start a run (message may be "-" for stdin)
   status <run_id>                                         show a run's progress
-  wait <run_id> [--timeout <seconds>]                     block until the run ends, print its reply
+  wait <run_id> [--timeout <seconds>]                     block until the run ends (or asks a person), print it
   rename <session_id> <title>                             rename a session
   rename-workspace <workspace_id|dir> <title>             rename a workspace (sidebar title)
   activity <session_id>                                   what the session is doing now (turn, sub-agents, jobs)
   cancel <run_id> | --session <id>                        stop the session's turn, sub-agents and jobs
-  runs [--limit <n>]                                      list recent runs`
+  queued <run_id> edit <message...> | remove | steer      change a message still waiting in Harness's queue
+  answer <run_id> '<answers JSON>'                         answer the questions a run is waiting on
+  runs [--session <id>] [--limit <n>]                     list recent runs`
 
 function parse(argv) {
   const flags = {}, rest = []
@@ -62,12 +64,17 @@ async function main() {
       return print(await core.api.status({ run_id: rest[0] }))
     case 'wait': {
       const st = await core.api.wait({ run_id: rest[0], timeout_s: Number(flags.timeout) || 24 * 3600 })
-      print({ run_id: st.run_id, state: st.state, session_id: st.session_id, timed_out: !!st.timed_out, error: st.error, final_text: st.final_text })
-      process.exitCode = st.state === 'completed' ? 0 : 1
+      print({ run_id: st.run_id, state: st.state, session_id: st.session_id, timed_out: !!st.timed_out, error: st.error, final_text: st.final_text,
+        ...(st.needs_input ? { needs_input: st.needs_input, question: st.question, hint: st.question ? 'The run asks the user something: answer with dsh_answer (or dsh-baton answer), only by your own judgment if the user allowed that; otherwise show the user the questions with your own recommendation and a reason from your own judgment of the question and the task ("it is marked recommended" is not a reason) and ask first. Then wait again.' : 'The run waits for a person in the Harness UI. Tell the user, then wait again.' } : {}) })
+      process.exitCode = st.state === 'completed' ? 0 : st.needs_input ? 3 : 1
       return
     }
     case 'cancel':
       return print(await core.api.cancel(rest[0]?.startsWith('session') || flags.session ? { session_id: flags.session ?? rest[0] } : { run_id: rest[0] }))
+    case 'queued':
+      return print(await core.api.update_queued({ run_id: rest[0], action: rest[1], ...(rest[1] === 'edit' ? { message: rest.slice(2).join(' ') } : {}) }))
+    case 'answer':
+      return print(await core.api.answer({ run_id: rest[0], answers: JSON.parse(rest.slice(1).join(' ')) }))
     case 'rename':
       return print(await core.api.rename_session({ session_id: rest[0], title: rest.slice(1).join(' ') }))
     case 'rename-workspace':
@@ -76,7 +83,7 @@ async function main() {
     case 'activity':
       return print(await core.api.activity({ session_id: rest[0] }))
     case 'runs':
-      return print(await core.api.list_runs({ limit: Number(flags.limit) || 10 }))
+      return print(await core.api.list_runs({ limit: Number(flags.limit) || 10, session_id: flags.session }))
     default:
       console.error(USAGE)
       process.exitCode = cmd ? 2 : 0

package/src/core.mjs

@@ -506,10 +506,12 @@ export function cancelRun(runId) {
   return { ...st, state: 'cancelling' }
 }
 
-export function listRuns({ limit = 10 } = {}) {
+export function listRuns({ limit = 10, session_id } = {}) {
   if (!fs.existsSync(runsDir())) return []
-  return fs.readdirSync(runsDir()).filter((d) => d.startsWith('run-')).sort().reverse().slice(0, limit)
-    .map((id) => { try { return runStatus(id, { tail: 0 }) } catch { return null } }).filter(Boolean)
+  const ids = fs.readdirSync(runsDir()).filter((d) => d.startsWith('run-')).sort().reverse()
+  return (session_id ? ids : ids.slice(0, limit))
+    .map((id) => { try { return runStatus(id, { tail: 0 }) } catch { return null } })
+    .filter((r) => r && (!session_id || r.session_id === session_id)).slice(0, limit)
 }
 
 // ---------------------------------------------------------------------------
@@ -568,8 +570,27 @@ export const api = {
     if (!(await useHost())) throw new Error('Session activity needs the dsh-baton-host plugin running inside DeepSeek Harness.')
     return hostCall('activity', { session_id })
   },
-  async list_runs({ limit = 10 } = {}) {
-    const host = (await hostAvailable()) ? tag('host', await hostCall('list_runs', { limit })) : []
-    return [...host, ...tag('headless', listRuns({ limit }))].sort((x, y) => String(y.started_at).localeCompare(String(x.started_at))).slice(0, limit)
+  async update_queued(a) {
+    if (!(await useHost())) throw new Error('Changing a queued message needs the dsh-baton-host plugin running inside DeepSeek Harness.')
+    try {
+      return await hostCall('update_queued', a)
+    } catch (error) {
+      if (!/Unknown method: update_queued/.test(error?.message)) throw error
+      throw new Error(`The Harness plugin dsh-baton-host ${hostVersion ?? ''} is too old to change queued messages; this MCP server is ${VERSION}. Update the plugin in Harness: Plugins → dsh-baton-host → Uninstall, then Add plugin → dsh-baton-host@${VERSION}.`.replace('  ', ' '))
+    }
+  },
+  async answer(a) {
+    if (!(await useHost())) throw new Error('Answering a question needs the dsh-baton-host plugin running inside DeepSeek Harness.')
+    try {
+      return await hostCall('answer', a)
+    } catch (error) {
+      if (!/Unknown method: answer/.test(error?.message)) throw error
+      throw new Error(`The Harness plugin dsh-baton-host ${hostVersion ?? ''} is too old to answer questions; this MCP server is ${VERSION}. Answer in the Harness window, or update the plugin: Plugins → dsh-baton-host → Uninstall, then Add plugin → dsh-baton-host@${VERSION}.`.replace('  ', ' '))
+    }
+  },
+  async list_runs({ limit = 10, session_id } = {}) {
+    // An older plugin ignores session_id, so the host's runs are filtered here too.
+    const host = (await hostAvailable()) ? tag('host', await hostCall('list_runs', { limit: session_id ? 100 : limit, session_id })).filter((r) => !session_id || r.session_id === session_id) : []
+    return [...host, ...tag('headless', listRuns({ limit, session_id }))].sort((x, y) => String(y.started_at).localeCompare(String(x.started_at))).slice(0, limit)
   },
 }

package/src/server.mjs

@@ -32,6 +32,11 @@ const codeModeYield = () => {
 }
 const NO_POLL = 'While waiting, make no other calls: no dsh_status, dsh_session_activity or dsh_read_session, and do not list or read the target folder or files to check progress. The final dsh_wait result carries the reply of the run; check files only after the run ends, if needed.'
 const ARCHIVED = 'Sessions not in dsh_list_sessions are archived or gone: do not look for them on disk.'
+// What to do when a run stops to ask a person (dsh_wait, wait_command and the instructions say it).
+const ASKED = 'If the user told you to decide such questions yourself, answer with dsh_answer by your own judgment (the recommended option is only a suggestion). Otherwise show the user the questions and options, add your own recommendation with a short reason drawn from your own judgment of the question and the task (it may differ from the option marked recommended; "it is marked recommended" is not a reason), wait for their decision, then submit it with dsh_answer. Never answer on the user\'s behalf without that permission.'
+const NEEDS_INPUT_HINT = (st) => st.question
+  ? `The run stopped to ask the user ${st.question.count} question(s) (in question). ${ASKED} After answering, wait for the run again.`
+  : 'The run waits for something only a person can do in the Harness UI (an approval, for example). Tell the user, then wait for the run again.'
 
 // A shell command that blocks until a run ends and prints its reply. Run in the
 // background by a client that wakes the model when the command exits (Claude Code),
@@ -54,6 +59,7 @@ async function waitInChunks({ run_id }, progress) {
     const left = Math.ceil((deadline - Date.now()) / 1000)
     const t0 = Date.now()
     const st = await core.api.wait({ run_id, timeout_s: Math.max(1, Math.min(WAIT_CHUNK_S, left)) })
+    if (st.needs_input) return { ...st, hint: NEEDS_INPUT_HINT(st) }
     if (!st.timed_out) return st
     // Never spin: a chunk that came back early still takes a moment before the next one.
     if (Date.now() - t0 < 500) await new Promise((r) => setTimeout(r, 500))
@@ -62,7 +68,7 @@ async function waitInChunks({ run_id }, progress) {
         run_id, state: st.state, timed_out: true,
         ...(st.waiting_on ? { waiting_on: st.waiting_on } : {}),
         hint: st.state === 'waiting'
-          ? 'The run is waiting for a person to answer in the Harness UI. Tell the user, then call dsh_wait again.'
+          ? 'The run is still waiting for a person (see dsh_status for its question). Answer it with dsh_answer if you may, or tell the user; then call dsh_wait again.'
           : `Still ${st.state}. Call dsh_wait again with the same run_id, with no other calls in between and no progress note.`,
       }
     }
@@ -70,87 +76,133 @@ async function waitInChunks({ run_id }, progress) {
   }
 }
 
+// MCP tool annotations. Every tool only talks to the local Harness (no open world).
+const hints = (readOnlyHint, destructiveHint, idempotentHint) => ({ readOnlyHint, destructiveHint, idempotentHint, openWorldHint: false })
+const READ = hints(true, false, true)
+const EDIT = hints(false, false, true) // changes something, and the same call again changes nothing more
+const annotations = (title, h = READ) => ({ title, ...h })
+
 const TOOLS = [
   {
     name: 'dsh_list_workspaces',
+    annotations: annotations('List workspaces'),
     description: 'List the workspaces (project folders) in the DeepSeek Harness sidebar; dsh_list_sessions lists the sessions inside them and dsh_create_workspace adds one. Returns id, path, title and session_count for each; the id is the workspace_id for dsh_send and dsh_rename_workspace. Read-only. Needs the dsh-baton-host plugin.',
     inputSchema: { type: 'object', properties: {} },
     run: () => core.api.workspaces(),
   },
   {
     name: 'dsh_create_workspace',
+    annotations: annotations('Create workspace', EDIT),
     description: 'Add a folder to the DeepSeek Harness sidebar as a workspace without starting a session; dsh_list_workspaces only lists existing ones, and dsh_send with a cwd registers the folder by itself. Creates the folder unless create_dir is false. Idempotent: an already registered folder returns its existing workspace. Returns id, path, title and created (false when it already existed). Needs the dsh-baton-host plugin.',
     inputSchema: { type: 'object', required: ['path'], properties: { path: str('Absolute folder path (~ allowed)'), title: str('Sidebar title; defaults to the folder name'), create_dir: { type: 'boolean', description: 'Create the folder if missing', default: true } } },
     run: (a) => core.api.create_workspace(a),
   },
   {
     name: 'dsh_list_sessions',
+    annotations: annotations('List sessions'),
     description: `List saved DeepSeek Harness sessions (conversations), newest first, to find a session_id; dsh_list_runs lists only the messages sent through dsh_send. Returns session_id, title, cwd, updated_at, running and bridge_runs (active dsh-baton run ids) for each. There is no paging: the list stops at limit, so to see older sessions raise limit or narrow it with cwd or query. Read-only. ${ARCHIVED}`,
     inputSchema: { type: 'object', properties: { cwd: str('Only sessions of this workspace folder'), query: str('Case-insensitive text to match in title, folder or session id'), limit: int('Max sessions returned', 20), include_subagents: { type: 'boolean', description: 'Also list sub-agent sessions', default: false } } },
     run: (a) => core.api.list_sessions(a),
   },
   {
     name: 'dsh_read_session',
+    annotations: annotations('Read session'),
     description: 'Read what was said in one session (its past messages), to catch up before continuing it; dsh_session_activity shows what it is doing now and dsh_status follows one run. Returns title, cwd, total_messages and the last messages, each with role (user or assistant), time, text and the names of tools the assistant called (tool output is not included). Read-only.',
     inputSchema: { type: 'object', required: ['session_id'], properties: { session_id: str('Session id from dsh_list_sessions, e.g. session-…'), last: int('How many of the most recent messages to return; total_messages tells how many there are', 10) } },
     run: (a) => core.api.read_session(a),
   },
   {
     name: 'dsh_send',
-    description: 'Send a message to a DeepSeek Harness session and return at once with a run_id, without waiting for the reply; dsh_wait then waits for it. With session_id it continues that existing session (same context, no new session); with cwd or workspace_id it starts a new session there (a cwd that is not a workspace yet is registered in the sidebar first). The turn runs in the background. If the session is already working, mode followup (default) queues the message after the current turn and steer adds it to the running turn; each message gets its own run_id. The message is delivered verbatim as a user message, with no prefix or label added: write it in the language the user works in, self-contained (Harness does not see this conversation), and say who is asking only if it matters. Then wait for the reply with dsh_wait (or the wait_command it returns, where offered).',
-    inputSchema: { type: 'object', required: ['message'], properties: { message: str('The task or reply to send'), session_id: str('Existing session to continue'), cwd: str('Workspace folder for a new session'), workspace_id: str('Harness workspace for a new session (from dsh_list_workspaces)'), mode: { type: 'string', enum: ['followup', 'steer'], description: 'followup queues after the current turn (default); steer injects into a running turn', default: 'followup' } } },
+    annotations: annotations('Send message', hints(false, false, false)),
+    description: 'Send a message to a DeepSeek Harness session and return at once with a run_id, without waiting for the reply; dsh_wait then waits for it. With session_id it continues that existing session (same context, no new session); with cwd or workspace_id it starts a new session there (a cwd that is not a workspace yet is registered in the sidebar first). The turn runs in the background. If the session is already working, mode followup queues the message after the current turn and steer adds it to the running turn; each message gets its own run_id. Leave mode out to do what the user set in Harness (Settings, sending while busy: queue or steer); followup when that setting cannot be read. The result says which mode was used and why (mode_source: explicit, harness or default). A queued message can still be edited, removed or turned into a steer with dsh_update_queued. The message is delivered verbatim as a user message, with no prefix or label added: write it in the language the user works in, self-contained (Harness does not see this conversation), and say who is asking only if it matters. Then wait for the reply with dsh_wait (or the wait_command it returns, where offered).',
+    inputSchema: { type: 'object', required: ['message'], properties: { message: str('The task or reply to send'), session_id: str('Existing session to continue'), cwd: str('Workspace folder for a new session'), workspace_id: str('Harness workspace for a new session (from dsh_list_workspaces)'), mode: { type: 'string', enum: ['followup', 'steer'], description: "followup queues after the current turn; steer injects into a running turn. Omit to follow Harness's busy-send setting" } } },
     run: async (a) => {
       const st = await core.api.send({ ...a, sender: core.senderOf(core.setting('SENDER') || clientName) })
       // Codex has no wake-on-exit for shell commands: offered wait_command, it runs it in a
       // terminal and polls that, so it gets dsh_wait only.
-      if (isCodex()) return { ...st, hint: `Run started. Call dsh_wait with this run_id; it returns when the run ends. ${NO_POLL} ${codeModeYield()}` }
+      if (isCodex()) return { ...st, hint: `Run started. Call dsh_wait with this run_id; it returns when the run ends or stops to ask the user something. ${NO_POLL} ${codeModeYield()}` }
       return {
         ...st,
         wait_command: waitCommand(st.run_id),
-        hint: 'Run started. If you can run a shell command in the background and are woken when it exits (Claude Code: Bash with run_in_background), run wait_command that way: it ends when the run ends and prints the reply, with no polling. Otherwise call dsh_wait with this run_id.',
+        hint: 'Run started. If you can run a shell command in the background and are woken when it exits (Claude Code: Bash with run_in_background), run wait_command that way: it ends when the run ends, or stops to ask the user something, and prints the reply or the questions, with no polling. Otherwise call dsh_wait with this run_id.',
       }
     },
   },
   {
     name: 'dsh_status',
+    annotations: annotations('Run status'),
     description: 'Look once at one run sent with dsh_send, without waiting; dsh_wait waits for it to end and dsh_session_activity covers the whole session. Returns state (queued/running/waiting/completed/failed/cancelled, or interrupted when a Harness restart cut it short), session_id, recent events (text, tool calls), final reply, waiting_on when the turn is over but sub-agents or background jobs are still working, and human_interjections when someone typed in the Harness UI during the run (its result then reflects that input too). A one-off look, never a way to wait: to wait for the reply use dsh_wait, and if dsh_wait timed out, call dsh_wait again.',
     inputSchema: { type: 'object', required: ['run_id'], properties: { run_id: str('Run id from dsh_send'), tail: int('How many recent events', 20) } },
     run: (a) => core.api.status(a),
   },
   {
     name: 'dsh_wait',
-    description: () => `Wait for a run sent with dsh_send to end and return its final status and reply; dsh_status only looks once.${isCodex() ? '' : ' Prefer the background wait_command from dsh_send when your client can run background shell commands and wake you when they exit: it costs no turns while waiting.'} Each call waits up to ${waitSeconds()} s (set by the server to stay under this client's tool timeout); if the run is still going it returns timed_out: true with just the state: then call dsh_wait again with the same run_id, without summarising progress.${isCodex() ? ` ${NO_POLL} ${codeModeYield()}` : ''} Sends progress notifications while waiting when the client asks for them.`,
+    annotations: annotations('Wait for run'),
+    description: () => `Wait for a run sent with dsh_send to end and return its final status and reply; dsh_status only looks once.${isCodex() ? '' : ' Prefer the background wait_command from dsh_send when your client can run background shell commands and wake you when they exit: it costs no turns while waiting.'} It also returns at once when the run stops to ask a person: needs_input is answer (the questions are in question; relay them with your own recommendation and a reason from your own judgment of the task, not the recommended mark, then reply with dsh_answer) or harness-ui (an approval only a person can give in Harness). Each call waits up to ${waitSeconds()} s (set by the server to stay under this client's tool timeout); if the run is still going it returns timed_out: true with just the state: then call dsh_wait again with the same run_id, without summarising progress.${isCodex() ? ` ${NO_POLL} ${codeModeYield()}` : ''} Sends progress notifications while waiting when the client asks for them.`,
     inputSchema: { type: 'object', required: ['run_id'], properties: { run_id: str('Run id from dsh_send') } },
     run: (a, { progress }) => waitInChunks(a, progress),
   },
+  {
+    name: 'dsh_answer',
+    annotations: annotations('Answer question', hints(false, false, false)),
+    description: `Answer the questions a run sent with dsh_send is waiting on (Harness's ask_user_question, shown in dsh_wait / dsh_status as question); dsh_send sends a new message instead, and dsh_update_queued changes one still in the queue. Per question: choose option numbers or labels, text for a free-text answer (with a single choice it replaces the option), or skip. Several questions can be answered in one call or one at a time: the answer reaches Harness once every question has one (submitted: true; until then remaining lists the rest). The run then continues; wait for it again. Whoever answers first wins: if the user answers in the Harness window, this call reports there is no open question. ${ASKED}`,
+    inputSchema: {
+      type: 'object', required: ['run_id', 'answers'], properties: {
+        run_id: str('Run id that is waiting (needs_input: answer)'),
+        answers: {
+          type: 'array', description: 'One entry per question answered now', items: {
+            type: 'object', properties: {
+              id: str('Question id from question.questions[].id; may be left out when there is one question'),
+              choose: { type: 'array', items: { type: ['integer', 'string'] }, description: 'Option numbers (1 = first) or labels; one for a single-choice question' },
+              text: str('Free-text answer'),
+              skip: { type: 'boolean', description: 'Skip this question' },
+            },
+          },
+        },
+      },
+    },
+    run: (a) => core.api.answer(a),
+  },
   {
     name: 'dsh_rename_session',
+    annotations: annotations('Rename session', EDIT),
     description: 'Set the title of one DeepSeek Harness session (a conversation); dsh_rename_workspace renames a workspace (project folder) instead. Only the title changes; the conversation and any running turn are untouched. Can be called again at any time to change it back or to something else. Returns session_id and the saved title.',
     inputSchema: { type: 'object', required: ['session_id', 'title'], properties: { session_id: str('Session id from dsh_list_sessions'), title: str('New title; surrounding spaces are trimmed and it must not be empty') } },
     run: (a) => core.api.rename_session(a),
   },
   {
     name: 'dsh_rename_workspace',
+    annotations: annotations('Rename workspace', EDIT),
     description: 'Set the sidebar title of a DeepSeek Harness workspace (project folder); dsh_rename_session renames a single session instead. The folder on disk is not moved or renamed. Identify it by workspace_id or path. Can be called again to change it back. Returns id, path and the saved title.',
     inputSchema: { type: 'object', required: ['title'], properties: { workspace_id: str('Workspace id from dsh_list_workspaces'), path: str('Workspace folder, used when workspace_id is not given'), title: str('New title; surrounding spaces are trimmed and it must not be empty') } },
     run: (a) => core.api.rename_workspace(a),
   },
   {
     name: 'dsh_session_activity',
+    annotations: annotations('Session activity'),
     description: 'Show what one session is doing right now, across all its work; dsh_status follows a single run and dsh_read_session shows past messages. Returns busy, activity (its running turn, sub-agents at any depth, background jobs and reminders) and bridge_runs (active dsh-baton runs). Read-only. Check it before dsh_send to a session that might be busy, or before dsh_cancel.',
     inputSchema: { type: 'object', required: ['session_id'], properties: { session_id: str('Session id from dsh_list_sessions') } },
     run: (a) => core.api.activity(a),
   },
   {
     name: 'dsh_cancel',
-    description: 'Stop everything a session is doing (running turn, sub-agents, background jobs, reminders), by run_id or session_id; the session itself is kept, and this is the only tool that stops work. It retries a few times until the session is quiet, then returns session_id, run (when run_id was given), attempts, still_busy, activity (whatever is still going) and queued_runs. Messages still waiting in the queue are not removed. Safe to repeat: on an idle session it does nothing and returns still_busy: false. Use dsh_session_activity first to see what would be stopped.',
+    annotations: annotations('Cancel session work', hints(false, true, true)),
+    description: 'Stop everything a session is doing (running turn, sub-agents, background jobs, reminders), by run_id or session_id; the session itself is kept, and this is the only tool that stops work. It retries a few times until the session is quiet, then returns session_id, run (when run_id was given), attempts, still_busy, activity (whatever is still going), queued_runs and removed_from_queue. Harness also drops the messages still waiting in the session queue: their runs end as cancelled and are listed in removed_from_queue; to drop just one queued message, use dsh_update_queued instead. Safe to repeat: on an idle session it does nothing and returns still_busy: false. Use dsh_session_activity first to see what would be stopped.',
     inputSchema: { type: 'object', properties: { run_id: str('Run id from dsh_send; stops the session that run belongs to'), session_id: str('Session id, to stop work dsh-baton did not start') } },
     run: (a) => core.api.cancel(a),
   },
+  {
+    name: 'dsh_update_queued',
+    annotations: annotations('Change queued message', hints(false, true, false)),
+    description: 'Change one message sent with dsh_send that is still waiting in Harness\'s queue behind a running turn; dsh_send sends a new one and dsh_cancel stops the whole session. action edit replaces its text with message, remove deletes it (its run ends as cancelled), steer moves it into the running turn now. Only for a run whose state is queued: once its message has reached the conversation it can no longer be changed, and the error says so. Returns the run (with message_preview after an edit) and the action taken.',
+    inputSchema: { type: 'object', required: ['run_id', 'action'], properties: { run_id: str('Run id from dsh_send of the queued message'), action: { type: 'string', enum: ['edit', 'remove', 'steer'], description: 'edit replaces the text, remove deletes the message, steer sends it into the running turn now' }, message: str('New text for action edit (plain text, not empty)') } },
+    run: (a) => core.api.update_queued(a),
+  },
   {
     name: 'dsh_list_runs',
-    description: 'List the runs sent through dsh_send (the latest 100 are kept), newest first, to recover a lost run_id or review past hand-overs; dsh_list_sessions lists Harness sessions instead. Returns run_id, session_id, state, started_at, ended_at, message_preview, final_text and error for each; dsh_status shows one run in detail. Read-only.',
-    inputSchema: { type: 'object', properties: { limit: int('Max runs returned', 10) } },
+    annotations: annotations('List runs'),
+    description: 'List the runs sent through dsh_send (the latest 100 are kept), newest first, to recover a lost run_id or review past hand-overs (session_id narrows it to one session); dsh_list_sessions lists Harness sessions instead. Returns run_id, session_id, state, started_at, ended_at, message_preview, final_text and error for each; dsh_status shows one run in detail. Read-only.',
+    inputSchema: { type: 'object', properties: { session_id: str('Only runs sent to this session'), limit: int('Max runs returned', 10) } },
     run: (a) => core.api.list_runs(a),
   },
 ]
@@ -171,7 +223,7 @@ async function handle(req) {
         protocolVersion: PROTOCOLS.includes(asked) ? asked : PROTOCOLS[0],
         capabilities: { tools: {} },
         serverInfo: SERVER,
-        instructions: `Hands tasks to a local DeepSeek Harness and passes the results back. Typical flow: dsh_list_workspaces (or dsh_create_workspace) to pick a folder, dsh_list_sessions to find a session, dsh_send {session_id, message} to continue it (or {cwd, message} to start one), then wait for the reply: ${isCodex() ? 'call dsh_wait with the run_id until it returns the final state (not dsh_status)' : 'run the wait_command it returns as a background shell command if your client wakes you when one exits, otherwise call dsh_wait'}. Then dsh_read_session to read the conversation, dsh_session_activity to see what a session is doing, and dsh_cancel to stop it; dsh_list_runs recovers a lost run_id. A run in state "waiting" needs a person to answer in the Harness UI. ${ARCHIVED}`,
+        instructions: `Hands tasks to a local DeepSeek Harness and passes the results back. Typical flow: dsh_list_workspaces (or dsh_create_workspace) to pick a folder, dsh_list_sessions to find a session, dsh_send {session_id, message} to continue it (or {cwd, message} to start one), then wait for the reply: ${isCodex() ? 'call dsh_wait with the run_id until it returns the final state (not dsh_status)' : 'run the wait_command it returns as a background shell command if your client wakes you when one exits, otherwise call dsh_wait'}. Then dsh_read_session to read the conversation, dsh_session_activity to see what a session is doing, dsh_update_queued to edit or withdraw a message still waiting in its queue, and dsh_cancel to stop it; dsh_list_runs recovers a lost run_id. A run that stops to ask the user something ends the wait at once with needs_input and the questions; answer with dsh_answer. ${ASKED} ${ARCHIVED}`,
       }
     }
     case 'ping':