Skip to main content
Glama

Start conversation

dsh_start

Creates a disk-backed DSH coding-agent conversation that survives crashes and restarts, returning its ID and title so you can dispatch work to it later.

Instructions

Create a DSH conversation: a coding agent you can keep working with. The conversation lives on disk and the process is only a cache; if the process is reaped or crashes, the next dispatch brings it back with ACP session/resume and nothing is lost. Returns the conversation_id and the conversation title. Dispatch work to it with dsh_send.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "dsh_start"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdNoAbsolute path of the workspace. It decides the agent's working directory, where AGENTS.md and skills are discovered, and the root the sandbox may write to. A single local root can supply the default in a legacy MCP client. Pass cwd explicitly with multiple roots, no roots, or MCP 2026-07-28.
modelNoModel name (for example deepseek-flash). When set, provider must be set too.
reviewNoCaller review policy, default advisory. advisory: every dispatch result and sentinel carries a review ticket (checklist, evidence, and the dsh_review entry point) but **does not block** later dispatches; off: no ticket. A single dsh_send can override it.
providerNoModel provider name (for example deepseek-official). Leave empty for the profile default.
isolationNoWorkspace isolation, default none (work directly in cwd). worktree = create a new worktree and branch `dsh/<time>` for the git repository cwd is in and work there, leaving the main checkout alone, so you (the caller) can keep editing the original directory at the same time. It starts from the current HEAD: uncommitted changes in the main checkout are not carried over, and the new worktree has no node_modules or other dependencies, so DSH may reinstall them. The changes stay on that branch for you to review and merge yourself; dsh_release(forget=true) deletes the worktree directory if it is clean (the branch is kept).
keep_aliveNotrue = this conversation's process is exempt from idle-TTL and MAX_LIVE reaping (for a long-lived conversation that must keep holding the write lock). Default false: after 10 idle minutes the process is reaped and its memory freed, and the next dispatch resumes it with nothing lost. With true, remember to dsh_release when done, or it keeps a DSH process (about 300-480 MB) forever.
permissionNoPermission tier. Default workspace-write. read-only suits untrusted material such as malware samples; workspace-write limits writes through the DSH sandbox. Escalation requests follow the machine approval policy. The tier is fixed at creation. A resumed DSH session keeps the permission it recorded, so changing this argument later does not change an existing conversation; create a new one to switch tiers. (The tier is really enforced: it comes from the environment passed at spawn time, and test/permission.mjs checks each tier against the session's own record.)
title_hintNoA readable label for the conversation (up to 200 characters). DSH's own title is a truncated prefix of the first message (about 13-15 characters) and is shown first; the value given here is not overwritten and comes back in dsh_get / dsh_start as the title hint.
on_approvalNoHow approval requests are handled. **read-only forces auto-deny** (auto-allow or ask is rejected outright, because it would let DSH's sandbox escalation through). The default tier has a machine ceiling of auto-deny. Callers can choose a stricter policy. The operator sets DSH_MCP_APPROVAL to permit a less restrictive policy. ask leaves each request pending until you decide it with dsh_approval_decide.
reasoning_effortNoReasoning effort, default max. ACP's own default is "Provider default" (unset); this server sets max explicitly. Lower it to save money.

Output Schema

NameRequiredDescriptionDefault
cwdYes
permissionYes
on_approvalYes
conversation_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv0.7.1
    • changedInput schema / properties / cwd / description
      Previous value: -"Absolute path of the workspace. It decides the agent's working directory, where AGENTS.md and skills are discovered, and the root the sandbox may write to. **When omitted, the project the client currently has open is used** (MCP roots), so the work happens in the project you see in the client; an explicit value is only required when the client has no roots support or reports none. Do not pass the user's home directory itself: DSH's ACL sandbox cannot start there."New value: +"Absolute path of the workspace. It decides the agent's working directory, where AGENTS.md and skills are discovered, and the root the sandbox may write to. A single local root can supply the default in a legacy MCP client. Pass cwd explicitly with multiple roots, no roots, or MCP 2026-07-28."
    • addedInput schema / properties / isolation
      Added value: +{
      +  "description": "Workspace isolation, default none (work directly in cwd). worktree = create a new worktree and branch `dsh/<time>` for the git repository cwd is in and work there, leaving the main checkout alone, so you (the caller) can keep editing the original directory at the same time. It starts from the current HEAD: uncommitted changes in the main checkout are not carried over, and the new worktree has no node_modules or other dependencies, so DSH may reinstall them. The changes stay on that branch for you to review and merge yourself; dsh_release(forget=true) deletes the worktree directory if it is clean (the branch is kept).",
      +  "enum": [
      +    "none",
      +    "worktree"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / on_approval / description
      Previous value: -"How approval requests are handled. **read-only forces auto-deny** (auto-allow or ask is rejected outright, because it would let DSH's sandbox escalation through); other tiers default to auto-allow. ask leaves each request pending until you decide it with dsh_approval_decide."New value: +"How approval requests are handled. **read-only forces auto-deny** (auto-allow or ask is rejected outright, because it would let DSH's sandbox escalation through). The default tier has a machine ceiling of auto-deny. Callers can choose a stricter policy. The operator sets DSH_MCP_APPROVAL to permit a less restrictive policy. ask leaves each request pending until you decide it with dsh_approval_decide."
    • changedInput schema / properties / permission / description
      Previous value: -"Permission tier. Default workspace-write. read-only suits untrusted material such as malware samples; workspace-write lets DSH's sandbox limit where writes can go, and requests to go beyond it are auto-allowed by default (pass on_approval=ask to have them wait for the caller). **The tier is fixed at creation**: by design a resumed DSH session keeps the permission it recorded, so changing this argument later does not change an existing conversation; create a new one to switch tiers. (The tier is really enforced: it comes from the environment passed at spawn time, and test/permission.mjs checks each tier against the session's own record.)"New value: +"Permission tier. Default workspace-write. read-only suits untrusted material such as malware samples; workspace-write limits writes through the DSH sandbox. Escalation requests follow the machine approval policy. The tier is fixed at creation. A resumed DSH session keeps the permission it recorded, so changing this argument later does not change an existing conversation; create a new one to switch tiers. (The tier is really enforced: it comes from the environment passed at spawn time, and test/permission.mjs checks each tier against the session's own record.)"
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "conversation_id": {
      +      "type": "string"
      +    },
      +    "cwd": {
      +      "type": "string"
      +    },
      +    "on_approval": {
      +      "type": "string"
      +    },
      +    "permission": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "conversation_id",
      +    "cwd",
      +    "permission",
      +    "on_approval"
      +  ],
      +  "type": "object"
      +}
  2. Changed9 schema fields changedv0.6.8
    • changedInput schema / properties / cwd / description
      Previous value: -"工作区绝对路径。决定 agent 的工作目录、AGENTS.md/技能的发现范围、以及沙箱可写根。**省略时自动用客户端当前打开的项目目录**(MCP roots),这样客户端里看到哪个项目就在这里干活;客户端不支持 roots、或 roots 为空时才会要求你显式传入。别传用户家目录本身 —— 那里会让 DSH 的 ACL 沙箱起不来。"New value: +"Absolute path of the workspace. It decides the agent's working directory, where AGENTS.md and skills are discovered, and the root the sandbox may write to. **When omitted, the project the client currently has open is used** (MCP roots), so the work happens in the project you see in the client; an explicit value is only required when the client has no roots support or reports none. Do not pass the user's home directory itself: DSH's ACL sandbox cannot start there."
    • changedInput schema / properties / keep_alive / description
      Previous value: -"true = 这个会话的进程不受空闲 TTL / MAX_LIVE 回收(用于\"必须一直握住写锁\"的长期会话)。默认 false:空闲 10 分钟后进程会被回收、内存释放,下次派活自动 resume(对话不丢)。设 true 时请记得用完 `dsh_release`,否则它会一直占着一个 DSH 进程(约 300–480MB)。"New value: +"true = this conversation's process is exempt from idle-TTL and MAX_LIVE reaping (for a long-lived conversation that must keep holding the write lock). Default false: after 10 idle minutes the process is reaped and its memory freed, and the next dispatch resumes it with nothing lost. With true, remember to dsh_release when done, or it keeps a DSH process (about 300-480 MB) forever."
    • changedInput schema / properties / model / description
      Previous value: -"模型名(如 deepseek-flash)。指定时必须同时给 provider。"New value: +"Model name (for example deepseek-flash). When set, provider must be set too."
    • changedInput schema / properties / on_approval / description
      Previous value: -"审批处理策略。**read-only 强制 auto-deny**(传 auto-allow/ask 会被直接拒绝,否则会放行 DSH 的 sandbox 提权);其余档位默认 auto-allow。ask 会把审批挂起,需用 dsh_approval_decide 裁决。"New value: +"How approval requests are handled. **read-only forces auto-deny** (auto-allow or ask is rejected outright, because it would let DSH's sandbox escalation through); other tiers default to auto-allow. ask leaves each request pending until you decide it with dsh_approval_decide."
    • changedInput schema / properties / permission / description
      Previous value: -"权限档。默认 workspace-write。read-only 适合分析不信任样本(如恶意软件);workspace-write 由 DSH 沙箱限制可写范围,越界请求默认 auto-allow,想在调用方挂起审批请传 on_approval=ask。**档位在创建时定下**:DSH 设计上\"resume 的会话保留它自己记录的权限\",所以事后改这个参数不会改变已有会话,要换档需新建。(本档位是**真实生效**的 —— 由启动时传入的 env 决定,并有 test/permission.mjs 对着会话自己的记录逐档核验。)"New value: +"Permission tier. Default workspace-write. read-only suits untrusted material such as malware samples; workspace-write lets DSH's sandbox limit where writes can go, and requests to go beyond it are auto-allowed by default (pass on_approval=ask to have them wait for the caller). **The tier is fixed at creation**: by design a resumed DSH session keeps the permission it recorded, so changing this argument later does not change an existing conversation; create a new one to switch tiers. (The tier is really enforced: it comes from the environment passed at spawn time, and test/permission.mjs checks each tier against the session's own record.)"
    • changedInput schema / properties / provider / description
      Previous value: -"模型提供方名(如 deepseek-official)。留空用 profile 默认。"New value: +"Model provider name (for example deepseek-official). Leave empty for the profile default."
    • changedInput schema / properties / reasoning_effort / description
      Previous value: -"思考深度,默认 max。注意 ACP 自身的默认是\"Provider default\"(不设),本服务会显式设成 max。想省钱可调低。"New value: +"Reasoning effort, default max. ACP's own default is \"Provider default\" (unset); this server sets max explicitly. Lower it to save money."
    • changedInput schema / properties / review / description
      Previous value: -"调用方审核策略,默认 advisory。advisory:每次派活的结果/哨兵都会附审核单(核验清单 + 证据 + dsh_review 入口),但**不阻塞**后续派活;off:不生成审核单。可被单次 dsh_send 覆盖。"New value: +"Caller review policy, default advisory. advisory: every dispatch result and sentinel carries a review ticket (checklist, evidence, and the dsh_review entry point) but **does not block** later dispatches; off: no ticket. A single dsh_send can override it."
    • changedInput schema / properties / title_hint / description
      Previous value: -"可读的会话标签(最长 200 字)。注意 DSH 自己的标题是首条消息的截断前缀(约 13–15 字),会优先显示;这里给的值不会被覆盖,而是在 dsh_get / dsh_start 里作为「标题提示」一并返回。"New value: +"A readable label for the conversation (up to 200 characters). DSH's own title is a truncated prefix of the first message (about 13-15 characters) and is shown first; the value given here is not overwritten and comes back in dsh_get / dsh_start as the title hint."
  3. Changed8 schema fields changedv0.5.1
    • changedInput schema / properties / cwd / description
      Previous value: -"工作区绝对路径。决定 agent 的工作目录、AGENTS.md/技能的发现范围、以及沙箱可写根。"New value: +"工作区绝对路径。决定 agent 的工作目录、AGENTS.md/技能的发现范围、以及沙箱可写根。**省略时自动用客户端当前打开的项目目录**(MCP roots),这样客户端里看到哪个项目就在这里干活;客户端不支持 roots、或 roots 为空时才会要求你显式传入。别传用户家目录本身 —— 那里会让 DSH 的 ACL 沙箱起不来。"
    • addedInput schema / properties / keep_alive
      Added value: +{
      +  "description": "true = 这个会话的进程不受空闲 TTL / MAX_LIVE 回收(用于\"必须一直握住写锁\"的长期会话)。默认 false:空闲 10 分钟后进程会被回收、内存释放,下次派活自动 resume(对话不丢)。设 true 时请记得用完 `dsh_release`,否则它会一直占着一个 DSH 进程(约 300–480MB)。",
      +  "type": "boolean"
      +}
    • changedInput schema / properties / on_approval / description
      Previous value: -"审批处理策略。默认 read-only → auto-deny,其余 → auto-allow。ask 会把审批挂起,需用 dsh_approval_decide 裁决。"New value: +"审批处理策略。**read-only 强制 auto-deny**(传 auto-allow/ask 会被直接拒绝,否则会放行 DSH 的 sandbox 提权);其余档位默认 auto-allow。ask 会把审批挂起,需用 dsh_approval_decide 裁决。"
    • changedInput schema / properties / permission / description
      Previous value: -"权限档。默认 danger-full-access。read-only 适合分析不信任样本(如恶意软件);workspace-write 越界操作会冒泡为待决审批。**档位在创建时定下**:DSH 设计上\"resume 的会话保留它自己记录的权限\",所以事后改这个参数不会改变已有会话,要换档需新建。(本档位是**真实生效**的 —— 由启动时传入的 env 决定,并有 test/permission.mjs 对着会话自己的记录逐档核验。)"New value: +"权限档。默认 workspace-write。read-only 适合分析不信任样本(如恶意软件);workspace-write 由 DSH 沙箱限制可写范围,越界请求默认 auto-allow,想在调用方挂起审批请传 on_approval=ask。**档位在创建时定下**:DSH 设计上\"resume 的会话保留它自己记录的权限\",所以事后改这个参数不会改变已有会话,要换档需新建。(本档位是**真实生效**的 —— 由启动时传入的 env 决定,并有 test/permission.mjs 对着会话自己的记录逐档核验。)"
    • addedInput schema / properties / review
      Added value: +{
      +  "description": "调用方审核策略,默认 advisory。advisory:每次派活的结果/哨兵都会附审核单(核验清单 + 证据 + dsh_review 入口),但**不阻塞**后续派活;off:不生成审核单。可被单次 dsh_send 覆盖。",
      +  "enum": [
      +    "off",
      +    "advisory"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / properties / title_hint / description
      Previous value: -"可选的标题提示(DSH 的标题由首条消息自动生成,这里只是兜底显示)。"New value: +"可读的会话标签(最长 200 字)。注意 DSH 自己的标题是首条消息的截断前缀(约 13–15 字),会优先显示;这里给的值不会被覆盖,而是在 dsh_get / dsh_start 里作为「标题提示」一并返回。"
    • addedInput schema / properties / title_hint / maxLength
      Added value: +200
    • changedInput schema / required
      Previous value: -[
      -  "cwd"
      -]New value: +[]
  4. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses a genuinely non-obvious lifecycle trait that annotations cannot express: the conversation lives on disk while the process is only a cache, so reaping or a crash costs nothing because the next dispatch resumes the ACP session. It also states the return values (conversation_id and title) and the handoff tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences, front-loaded with the purpose, then the durability model, then the return value and next step. Efficient, with only the light "a coding agent you can keep working with" framing as minor flourish.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema, annotations, and 100% schema coverage, the description supplies what structured fields cannot: the durable-session model and the dispatch handoff. It could have pointed at dsh_release/dsh_get for the keep_alive and inspection paths, but nothing required to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with all ten parameters richly documented (including keep_alive memory cost, isolation worktree behavior, and permission being fixed at creation), so the schema carries parameter meaning. The description adds no parameter-level guidance of its own, making 3 the correct baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

A specific verb and resource ("Create a DSH conversation") framed as a persistent coding agent, plus the immediate follow-up path ("Dispatch work to it with dsh_send"). An agent can distinguish this creation tool from dsh_send/dsh_get/dsh_list without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes follow-up work to dsh_send, which is the main when-to-use signal, and the creation verb makes the initial use case unambiguous. It stops short of naming exclusions, e.g. that existing conversations should be reached via dsh_get/dsh_list rather than creating a new one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.