运行：命令行与运行时

前半页写调用方怎么运行 agentrun：命令行选项、一次运行的顺序、启动前检查、doctor 与退出码。后半页每个运行时一节：agentrun 用什么参数启动它、它的原始输出怎么映射到统一事件、什么情况算失败。运行时的参数与行为来自实测，写明了实测的版本；运行时升级后要重新核对。原始输出的完整字段见 claude-code 事件流与 pi 事件流两页字段参考。

代码位置

每个运行时一个 Adapter 实现。check_args 在启动前检查只对某个运行时有要求的参数，例如 pi 的 --model 格式与 codex 不支持的 --max-turns、--max-tokens 与它挡不住的 --deny-read 路径。launch 返回 Launch（argv、标准输入内容、环境变量，以及记录 agentrun 用哪种沙箱包裹了命令的 wrapped 与适配器创建的私有目录 private_dirs）。运行框架按 wrapped 是否为 bubblewrap 决定第一个信号发给谁（见进程、信号与超时），过滤代理放行的模型服务主机取自 runtime::service_hosts，与 doctor 用同一个函数。translate 把运行时的一行原始输出转成零个或多个 Record，failure 在运行时退出后按本页各节的「失败判定」返回 Failure：Message 给出 detail，Unexplained 表示没有说明，由运行框架先看包裹命令是否启动失败，再取标准错误。适配器给出的说明为空字符串时按 Unexplained 处理。transcript 在运行时退出后返回这次运行留下的会话记录：会话 id 与要移进 --session-dir 的文件和目录；没有给出 --session-dir 或运行时没有留下记录时返回 None，见保存与继续会话。运行框架 src/run/ 不认识任何运行时的字段，理由：运行框架的流程对每个运行时相同；运行时之间的差别写在适配器里，以及 src/runtime/mod.rs 里与 doctor 共用、按 Runtime 分支的函数（min_version、service_hosts、proxy_needed、sandbox_state、default_denied_reads 等），另有 Session::assemble、sandbox::check、credential::write_session_credential 三个按 Runtime 分支的函数，运行框架只把 Runtime 传给它们。

按运行时分支一律用列出全部运行时的 match，不用 ==、!= 或带 _ 的分支；要遍历所有运行时时用 Runtime::value_variants()，不另写运行时列表。理由：新增一个运行时时，编译器会列出每个要补上的地方。

命令行界面

核心子命令有 agentrun claude-code、agentrun codex、agentrun pi、agentrun dsh。四个运行时子命令接受同一组选项。

agentrun claude-code --prompt "给 parse 模块补测试并修复失败"
agentrun pi --model deepseek/deepseek-flash --network custom --allow-host pypi.org --prompt-file task.md
agentrun codex --sandbox off --format jsonl --timeout 600 < task.md

agentrun <运行时> --help 把选项分成 Prompt、Model and limits、Sandbox, network and reads、Session environment、Saved sessions、Output 六组，逐项说明 --sandbox、--network 与 --format 的取值，末尾写出退出码与使用指南的链接；-h 给出每项一行的简表。分组名是 src/cli.rs 里的常量。

任何输出都只写变量名，不写变量的值，PATH 除外。四个运行时都从标准输入读提示词，所以提示词不出现在 start 事件的 argv 里，也不出现在 --dry-run 与 --debug 打印的命令里。

agentrun 自己写出的文字都用英文：detail、标准错误里的说明、text 与 rich 格式里的固定词、[note] 提示与 doctor 的输出。运行时与模型给出的内容（提示词、模型的文字、运行时的错误信息）原样输出。理由：命令行解析使用现成的库，它的错误信息是英文，全部输出用同一种语言。

启动前检查失败时，写到标准错误的一行是 agentrun: 加 detail，见启动前检查。--dry-run 写到标准输出、--debug 写到标准错误，每项一行，格式是 项目名: 值，--debug 的每行前面另加 [debug] 。命令的每个参数按 shell 规则加引号。

agentrun variables 一行列出调用方环境里以 AGENTRUN_ 开头的变量名，它们只给 agentrun 自己用，不进入会话，见会话环境。deny read 一行列出 agent 不能读的路径，与 start 事件的 deny_read 相同，见读取限制。

另外有 agentrun doctor。在 后文 详细描述。

额外传递参数给运行时

-- 之后的所有参数原样传给运行时，用于工具没有提供选项的运行时功能。工具生成的参数在前，-- 之后的参数接在后面。多数运行时遇到同一个选项出现两次时以后一次为准，所以调用方的参数可以覆盖工具的设置。

可以覆盖的设置包括权限与沙箱设置。工具不阻止，只在 start 事件的 argv 里如实记录，这时安全保证由调用方负责。理由：用户需要为没有预料到的用途保留完整的控制。

调用方的参数可能让运行时输出工具不认识的事件，例如给 claude-code 传 --include-partial-messages 后，会多出逐字输出的 stream_event。这类事件不进入统一事件流，只写入 --raw 文件。

图片

--image FILE 把一个图片文件与提示词放在同一条用户消息里交给模型，可以重复，图片按给出的顺序排列，数量不限。agentrun 在启动前读出每个文件的全部内容，以下情形是用法错误：

• 文件不存在或读不了，detail 为 cannot read image <路径>: <系统错误>。
• 路径（跟随符号链接之后）不是普通文件，例如目录、FIFO、设备文件，detail 为 image <路径> is not a regular file。文件以非阻塞方式打开，再检查类型。理由：FIFO 会让打开一直阻塞，设备文件的大小是 0、读取没有尽头，这两种都发生在启动前检查里，--timeout 管不到。
• 文件超过 20 MiB（20971520 字节），detail 为 image <路径> is larger than the limit of 20971520 bytes。读取最多读到上限加 1 字节，按实际读到的长度判断。
• 文件不是 PNG、JPEG、GIF 或 WebP，detail 为 image <路径> is not a png, jpeg, gif or webp file (animated png and jpeg-ls are not supported)。类型按文件内容判断，不看扩展名，规则按 pi 1.2.0 识别图片的规则写：PNG 的第一个块必须是长度 13 的 IHDR，IDAT 之前出现 acTL 块（动画 PNG）时不接受；JPEG 第 4 个字节是 0xF7（JPEG-LS）时不接受。pi 只在文件的前 4100 字节里找 acTL，agentrun 检查整个文件，所以 acTL 在 4100 字节之后的动画 PNG 被 agentrun 拒绝，pi 却会接受。理由：pi 不认作图片的文件会被当成文本读进提示词，不报错，模型看不到图片。

运行时拿到的是 agentrun 读出的内容，不读调用方给的路径。claude-code 的图片直接写进标准输入；pi 与 codex 的图片先写成会话临时目录里的 image-N.扩展名（N 从 1 开始，扩展名按类型取 png、jpg、gif、webp，权限 0600），再把这个路径传给运行时。理由：沙箱打开时 agent 一定能读会话临时目录，调用方的图片可能在别的目录里。--dry-run 不写这些文件，命令里的路径写成 <tempdir>/image-1.png。各运行时的传法见 claude-code、pi、codex 三节。dsh 的 headless 模式只接受文字，给出 --image 时启动前按用法错误拒绝，detail 为 --image is not supported by dsh: its headless mode takes text only。

三个支持图片的运行时都没有更严的文件大小限制：claude-code 与 pi 把过大的图片缩小后交给模型（实测 48 MB、4000×4000 像素的 PNG），codex 读本地图片时不检查大小、超过 2048 像素时缩小（codex 源码 codex-rs/utils/image）。20 MiB 是 agentrun 自己的上限，理由：图片在启动前整个读进内存，claude-code 的图片还要按 base64 写进标准输入的一行 JSON，体积再增加三分之一。

prompt 事件的 images 按顺序列出调用方写的路径，不转成绝对路径，不写图片内容，见事件与输出。

一次运行的顺序

启动前检查

以下情形在启动运行时之前报错。标准输出只有一个 end 事件，status 为 rejected，detail 写出原因与修正方法；同一个原因另写一行 agentrun: <detail> 到标准错误；agentrun 以退出码 2 结束。格式是 text 或 rich、并且标准输出与标准错误都是终端时，不写标准错误这一行。理由：两路输出都在用户的终端上时，同一句话会出现两次；输出被重定向时，调用方从标准错误或 end 事件都能读到原因。

• 用法错误：未知子命令或选项、值不合法、codex 给出 --max-turns 或 --max-tokens、提示词来源冲突或为空、--prompt-file 读取失败、--image 读取失败、类型不对或超过上限、--cwd 或 --path 不存在、--raw 文件无法创建、只写 KEY 的 --env 在调用方环境里找不到、--allow-host 格式不对、--deny-read 以 ~ 开头、等于或包含运行需要的目录、运行 codex 时含 * ? [ ] { }、环境变量 AGENTRUN_SANDBOX 的值不是 on、relax、off 之一。
• --env-file 读取失败或格式错误。
• 在会话 PATH 里找不到运行时。
• 凭据写入失败。
• --session-dir 的目录创建失败，或 --resume 给出的会话在 --session-dir 里找不到。
• --sandbox on 时沙箱不可用，或 --network 要求的限制无法执行，见沙箱与网络。
• 过滤代理启动失败；pi 的服务商不在模型服务主机表里且用 --network none；dsh 的 DEEPSEEK_BASE_URL 读不出主机且用 --network none。
• 会话临时目录创建失败；适配器准备启动参数失败，包括 pi 的状态目录创建失败或 Seatbelt 配置文件写不出、codex 的登录文件不存在或私有目录创建失败、dsh 的会话环境里没有 DEEPSEEK_API_KEY 或私有目录与补丁文件写不出。

过滤代理启动失败先于 codex 登录文件与私有目录的检查：两者同时成立时，detail 是过滤代理那一条。

命令行解析失败时还不知道 --format 的值，所以先单独扫描一遍参数找 --format，找不到或值不合法时按默认格式输出这个 end。

命令行解析的错误说明由 clap 生成。usage_error_detail 去掉其中的 error: 前缀、Usage: 与 For more information 两部分，把剩下的各行连成一行：前一行以冒号结尾时用空格连接，冒号之后紧接着的缩进各行是一个列表，列表项之间用 , ，其余用 ; 。例如 the following required arguments were not provided: <HOST>, <PORT> 与 unexpected argument '--promt' found; tip: a similar argument exists: '--prompt'; tip: to pass '--promt' as a value, use '-- --promt'。完全没有参数时不解析命令行，把顶层帮助写到标准错误，以退出码 2 结束，不输出 end。有参数但没有子命令时（例如只有 --），detail 是常量 MISSING_COMMAND：no command given: use claude-code, codex, pi, dsh or doctor; see agentrun --help。理由：clap 自己的说明会列出只给 doctor 内部使用的 doctor-connect。--max-turns、--max-tokens 与 --timeout 的值不是正整数时，说明是 invalid value '0' for '--timeout <SECONDS>': expected a positive integer。

run::run 解析命令行后，把运行时子命令交给运行框架，把 doctor 与 doctor-connect 分别交给 doctor::run 与 doctor::connect。运行时子命令被拒绝时的 end 只由 run::run 输出。

轮数与 token 上限

--max-turns 与 --max-tokens 由 agentrun 自己计数，不传给运行时，claude-code、pi 与 dsh 接受同样的选项。理由：运行时自带的上限只有 claude-code 有，由 agentrun 计数时同一条命令可以在这几个运行时之间换。

• 一轮是主 agent 的一次模型调用。适配器在一次调用开始时输出 Record::CallStart：claude-code 是某个 parent_tool_use_id 下出现新的 message.id，pi 是 assistant 的 message_start，dsh 是 phase 为 step_start 的 status。Aggregator 只数 parent 为 null 的调用，parent 指向没见过的 subagent 时按主 agent 计，与其他事件的 parent 规则相同。主 agent 开始第 N+1 次调用时终止。claude-code 可能在这次调用的输出还没结束时就开始执行它请求的工具，所以这些工具可能已经开始执行；沙箱外的 Bash 命令用 setsid 启动，不在进程组里，由运行时退出后的进程树清理结束。理由：与 claude-code 自带的 --max-turns 计数相同；不按 usage 事件计数，因为 claude-code 的 usage 要等下一次调用开始才输出，按它计数时 claude-code 比 pi 多一轮。
• token 数是全部 usage 事件（含 subagent）的 input_tokens、output_tokens、cache_read_tokens、cache_write_tokens 之和，null 按 0 计。还没有输出 usage 事件的调用，按适配器输出的 Record::CallUsage 计入：claude-code 的 usage 要等下一次调用开始才输出，而每条 assistant 消息都带着这次调用到当时为止的用量，适配器每读到一条就输出一次，同一个 parent 的 usage 到达时取代它。运行框架每处理完一行原始输出检查一次，和超过 N 时终止，运行时退出后读到的剩余输出也照常检查；end.usage 里没有对应 usage 事件的那笔 haiku 调用（见事件与输出的用量一节）不计入。dsh 不输出 subagent 的事件，输出里只有主会话的用量，所以 dsh 的 --max-tokens 只计主 agent 的 token，需要严格限制 dsh 的 token 数时同时给出 --no-subagents。dsh 的 end.usage 是 usage 事件之和，与上限计数的范围相同，同样不含 subagent。pi 与 dsh 只在一次调用结束时报告这次调用的用量，最后一次调用的用量全部计入，所以一次很长的调用会让最终的 token 数明显超过 N（dsh 实测：上限 8000，结束时 11059）。
• 终止的方式与 --timeout 相同：向进程组发 SIGTERM，5 秒后 SIGKILL，见进程、信号与超时。超过上限时，运行时满足 finished 的条件，结果是 finished（例如最后一次调用使和超过 N，但运行时已经给出结果并以 0 退出）；不满足时 end.status 为 limit，退出码 4。是否发过 SIGTERM 不影响判定，理由：运行时可能在退出码已经定为 0、进程还没有结束时收到信号，agentrun 无法区分这种情况与还在运行的运行时，按是否发过信号判定时结果会随时机变化。这个判定依赖一个条件：运行时在完成之前被 SIGTERM 停止时，适配器不能把这次运行判为 finished，靠非 0 的退出码或缺少完成事件都可以。claude-code（>= 2.1.303）与 pi（>= 1.0.2）收到 SIGTERM 时都以 143 退出，Linux 与 macOS 上包裹与不包裹相同。dsh 收到 SIGTERM 时以 0 退出。在一轮中间被停止时它不再输出 turn_end，按 dsh 一节失败判定的第 4 条不满足 finished；在一轮刚结束时被停止时，它照常输出 completed 的 turn_end，随后输出 error 事件 session …: flush on a closed handle，按第 1 条同样不满足 finished（0.2.1-rc.2 实测，前一种 3 次、后一种 9 次，结果都是 limit）。适配器只看事件，dsh 在收到 SIGTERM 前已经输出 turn_end 并且之后没有 error 事件时，结果是 finished。所以被 agentrun 停止的运行一定是 limit，即使运行时当时已经输出了完整的回答，这时 end.result 照常取已经收到的内容。不满足这个条件的运行时要拒绝这两个选项：codex 在 Linux 上收到 SIGTERM 时以 0 退出，这是 codex 不接受这两个选项的理由之一。detail 写出是哪个上限、上限值与实际值，例如 --max-turns 3 reached: the main agent started turn 4、--max-tokens 50000 exceeded: 51234 tokens。两个上限在同一行原始输出上同时超过时，detail 写 --max-turns。
• 超时、上限与信号中先触发的一个决定怎样终止，之后的上限不再生效；上限触发后的宽限期内收到信号，结果是 interrupted。适配器要求终止运行时（例如 pi 的模型不一致）的那一行不检查上限。
• codex 给出任一选项都是用法错误（rejected，退出码 2），由 reject_limits 检查。codex 只在运行结束时输出一次用量（turn.completed），也没有调用开始的事件（codex 0.159.2 实测），agentrun 无法在运行中停止它。理由：停不住 agent 的上限会让调用方以为有保护，明确拒绝不会。

保存与继续会话

给出 --session-dir DIR 时，agentrun 在运行时退出后把这次运行的会话记录移到 DIR/<运行时名>/，end.session_id 是会话 id。下一次运行给出同一个 --session-dir 与 --resume <会话 id>，运行时接着这段会话继续：会话 id 不变，新内容追加到同一份记录。不给 --session-dir 时四个运行时都不保存会话。--resume 只从 DIR 读，不读用户自己的会话记录；codex、pi 与 dsh 运行期间把记录写在私有目录或会话临时目录里，claude-code 的新会话运行期间写在用户的配置目录里，见下表与配置与账号。

• DIR 与 DIR/<运行时名>/ 不存在时在启动前创建，新建的目录权限为 0700；DIR 是相对路径时相对 agentrun 自己的当前目录。目录在所有启动前检查通过之后才创建，--dry-run 与被拒绝的运行不创建目录。DIR 要放在工作目录与会话临时目录之外：沙箱里的 agent 能写这两处，DIR 在里面时 agent 能改写已保存的会话。沙箱运行、DIR 等于或在工作目录之内时（与 --deny-read 相同的包含判断，见读取限制；判断在创建 DIR 之后进行，所以 DIR 总是跟随符号链接展开后比较，第一次使用时也一样），运行照常进行，text 与 rich 格式在 start 的位置输出一行 [note] --session-dir DIR is inside the working directory. The agent can change the saved sessions；jsonl 格式没有这一行。不拒绝运行，理由：调用方可能有意把会话放在工作目录里，例如沙箱之外另有隔离时。会话临时目录每次新建、名字随机，DIR 不会在它里面，所以不检查。沙箱没有运行时不输出这一行，沙箱关闭的 [note] 已经说明 agentrun 不限制写入。
• 记录的文件名沿用运行时自己的文件名。--resume ID 在 DIR/<运行时名>/ 里找文件名以 ID.jsonl 结尾、且 ID 前面是文件名开头、_ 或 - 的文件；dsh 的记录是一个目录，找名为 session-ID 的目录。ID 必须是完整的会话 id，四个运行时的会话 id 都是 UUID（8-4-4-4-12 位十六进制），不是这个形式时启动前按 rejected 拒绝，detail 为 --resume "<ID>" is not a session id。理由：只要求文件名以 ID 结尾时，UUID 的最后一段也能匹配，end.session_id 与传给 codex 的 id 就不是真实的会话 id。只在这次运行时自己的子目录里找，用另一个运行时继续某个运行时保存的 id 同样找不到。找不到时启动前按 rejected 拒绝，detail 为 no saved <运行时名> session <ID> in <目录>；这个 id 在 DIR 里另一个运行时的子目录里找得到时，后面再加 ; it was saved by <运行时名>, continue it with agentrun <运行时名>，按 claude-code、codex、pi、dsh 的顺序取第一个找到的。
• 保存在运行时退出、进程组清理之后，end 输出之前进行。failed、interrupted、timeout 与 limit 的运行只要留下了记录也照样保存；运行时没有留下记录时 session_id 为 null。移动失败时标准错误多一行 agentrun: cannot save the session: <原因>. The session is kept in <路径>，session_id 为 null，status 不变。保存先把新记录放到目标旁边的 .<文件名>.agentrun-saving（同一个文件系统时改名，不在同一个文件系统时复制），完整放好之后才替换已保存的旧记录：文件直接改名覆盖，目录先把旧目录改名为 .<目录名>.agentrun-replaced，新目录改名到位后再删除旧目录。放置或替换失败时已保存的旧记录不变，放了一半的副本被删除，这一行末尾列出还没有保存的记录现在所在的路径，记录改名到暂存位置后替换失败时改回原处，会话临时目录与 codex 的私有目录在结束时保留，不删除。保存在两次改名之间中断时会留下 .<目录名>.agentrun-replaced，之后的 --resume 查找与保存在目标不存在时把它改回原名，目标存在时删除它。理由：继续会话后旧记录与新记录同名，先删旧记录再复制时，磁盘满或复制出错会同时丢掉两份。
• 继续时 claude-code、codex 与 pi 的 --cwd 可以与上一次不同，运行时在新的工作目录里工作（三个运行时实测）；dsh 的 --cwd 必须与第一次相同，见下表。--model 等选项每次照常传给运行时。
• 不支持同时继续同一个会话。两个运行同时 --resume 同一个 id 时，claude-code 的两份新内容交错写进同一个文件；codex、pi 与 dsh 后结束的那次覆盖先结束的那次。

• claude-code 的新会话写在用户的配置目录里，运行结束后才移走。理由：claude-code 不能把新会话直接写到别的位置（--resume 指向空文件、不存在的文件或只有元数据行没有对话的文件时都报 No conversation found，2.1.303 实测）；改 CLAUDE_CONFIG_DIR 会改变 claude-code 读登录信息的位置：Linux 上登录文件在配置目录里，macOS 上钥匙串里的登录条目名随配置目录改变（未实测）。代价是运行期间这份记录出现在用户自己的 claude --resume 列表里，agentrun 被 SIGKILL 时它留在那里。
• pi 与 dsh 的记录先写在会话临时目录里，运行结束后再移到 DIR。前提是 DIR 在工作目录与会话临时目录之外。理由：pi 与 dsh 整个进程在沙箱里，让它直接写 DIR 就要把 DIR 放进沙箱的可写范围，agent 就能改写其他会话的记录。claude-code 与 codex 的记录由运行时进程自己写，不经过 agentrun 的沙箱，agent 的工具写不到 DIR。
• 复制会话目录时只复制普通文件与目录，跳过符号链接和其他类型的条目；claude-code 的 <id>/ 是符号链接时不保存它；dsh 的 session-<id>/ 与它所在的 <由 cwd 转换的目录名>/ 是符号链接时不保存，DIR/dsh/session-<id> 是符号链接时 --resume 报找不到会话。理由：dsh 的记录目录在沙箱里可写，agent 能在里面放指向沙箱外文件的链接，agentrun 在沙箱外复制时如果跟随链接，就会把 agent 读不到的文件复制进会话记录，下一次运行时 agent 就能读到。

doctor 检查

agentrun doctor [运行时...] [--model ID] [--sandbox MODE] [--network MODE] [--allow-host HOST]... [--path DIR]... [--env KEY[=VALUE]]... [--env-file FILE]... [--json] [--debug]

按当前环境检查运行时能否使用。不写运行时时检查全部四个，顺序固定为 claude-code、codex、pi、dsh。各选项的含义与运行时子命令相同，保证检查的条件与实际运行一致；--model 只由 pi 与 dsh 的检查使用：pi 的登录检查把它与实际使用的模型比较，dsh 的登录检查用它调用一次模型；claude-code 与 codex 的登录检查不调用模型，不检查模型名是否存在；--path DIR 把目录加到会话 PATH 的前面，可以重复，目录不存在时按用法错误处理。开始检查前，doctor 对每个要检查的运行时调用适配器的 check_args，参数不符合要求时按用法错误处理，例如 pi 的 --model 格式。不写运行时时四个运行时都要通过这项检查，所以 doctor --model sonnet 会因为 pi 要求 provider/model 格式以退出码 2 结束，只检查 claude-code 时要写成 doctor claude-code --model sonnet。

每项结果为 ok、fail 或 skip。每个外部命令最多等 30 秒，超时按 fail 记并写明；doctor-connect 连接代理或目标最多等 10 秒。可执行文件没找到时，登录为 skip；沙箱与网络对 claude-code、pi 与 dsh 仍然检查，因为它们用的是 agentrun 自己的包裹与 doctor-connect，pi 与 dsh 的沙箱检查这时不启动运行时，说明里加 pi not started (executable not found) 或 dsh not started (executable not found)；对 codex 两项都为 fail，说明为 executable not found，因为它的沙箱与代理就是 codex 本身。默认输出每项一行，四列对齐；--json 输出一个数组，每项是 {runtime, check, status, detail}，被信号中断时输出已完成的项。沙箱检查失败时，说明里写明可能的原因与修正方法。

前两条命令在没有用户命名空间权限的 docker 容器里运行，第三条在 Cloud Managed 容器里运行。下面是 dsh 在 Cloud Managed 容器里的结果，dsh 的路径改成了短路径：

退出码

调用方只看退出码就能区分「环境未配置好」（2）和「agent 没有完成任务」（1）。退出码为 2 时，调用方不改环境直接重试不会成功。状态的判定顺序见end.status。

运行时版本

下面是 agentrun 要求的最低版本，agentrun doctor 的 executable 一项按它检查，见doctor 检查。最低版本是各运行时模块里的常量 MIN_VERSION，改这个列表时同时改常量与快速开始的表，单元测试会比较三处是否一致。运行时子命令启动前不检查版本，start 事件也不带版本：运行开始前拿到版本要多启动一次运行时。

• claude-code: >= 2.1.288
• pi: >= 1.0.1，npm 包 @earendil-works/pi-coding-agent
• codex: >= 0.159.2，权限配置与 --ignore-user-config 需要这个版本
• dsh: >= 0.2.1-rc.2，npm 包 @deepseek-ai/dsh。npm 的默认标签 latest 指向更早的 0.2.0-rc.2，要写明版本安装。dsh 要求 Node ^22.19.0 || >=24.0.0

claude-code

参数

<claude 的绝对路径> -p --output-format stream-json --verbose
  --input-format stream-json --replay-user-messages
  --permission-mode dontAsk|auto
  --setting-sources ""
  --strict-mcp-config
  [--no-session-persistence]
  --session-id <新生成的 UUID v4> | --resume <保存的会话文件>
  --tools Read,Edit,Write,Glob,Grep,Bash,Task
  --allowedTools <放行列表>
  [--settings <权限与沙箱设置>]
  [--model ID] [--effort LEVEL]
  <-- 之后的调用方参数>

• --setting-sources "" 不加载用户、项目与本地设置，工作目录里的 CLAUDE.md 不进入模型上下文（实测）。因此沙箱设置只来自 --settings。
• 会话环境设置 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1，关闭 auto-memory。理由：--setting-sources "" 不关闭它，claude-code 仍把用户的 ~/.claude/projects/<项目>/memory/MEMORY.md 放进模型上下文；设置这个变量后，请求里不再有这个文件的内容与 memory 的说明（claude 2.1.288 与 2.1.303 云端实测）。这个变量在 --env 之后设置，调用方不能用 --env 改回。
• --strict-mcp-config 不加载任何 MCP 服务器。
• 新会话的 --session-id 每次新生成。理由：在 Claude Code 会话里运行 agentrun 时，claude -p 子进程会继承父会话的 id，把记录写进父会话，只加 --no-session-persistence 不能避免。没有给出 --session-dir 时另加 --no-session-persistence；给出时不加，继续会话时用 --resume 代替 --session-id，见保存与继续会话。
• --tools 限定可用的内置工具，去掉网页工具与技能等。--allowedTools 放行列出的工具，不经权限判断。Bash 不在放行列表里：沙箱打开时由 autoAllowBashIfSandboxed 自动放行，沙箱没有运行时由 auto 模式逐条判断。只用 --tools 而不放行时，auto 模式会拒绝 Write，且结果仍报告成功（实测）。
• 沙箱打开时权限模式是 dontAsk，放行列表是 Read,Glob,Grep,Task 加上 Edit(//<cwd>/**)、Write(//<cwd>/**)、Edit(//<会话临时目录>/**)、Write(//<会话临时目录>/**)；沙箱没有运行时权限模式是 auto，放行列表是 Read,Edit,Write,Glob,Grep,Task。理由见沙箱与网络。规则里的绝对路径以 // 开头，只写一个 / 时规则不匹配（实测）；路径里的 \ * ? [ ] { } 前面加反斜杠，否则工作目录名里的 [1] 这类字符被当作通配符，Write 写不进工作目录（claude 2.1.303 云端实测）。
• 启动 subagent 的工具在参数与 system/init 的工具列表里叫 Task，在输出的 tool_use 里叫 Agent，两个名字都要识别。--no-subagents 从 --tools 与 --allowedTools 里去掉 Task，生效与否看 init 的工具列表里有没有 Task。
• --network full 时两个列表都加上 WebFetch 与 WebSearch；custom 时 --tools 加 WebFetch，--allowedTools 每个主机加一条 WebFetch(domain:HOST)。
• 提示词从标准输入传入，不在命令行里：写入一行 JSON {"type":"user","message":{"role":"user","content":"<提示词>"}}，然后关闭标准输入。--replay-user-messages 让 claude-code 把这条消息回显到输出里，agentrun 据此输出 prompt 事件。不加这两个选项时，输出里没有提示词。实测关闭标准输入后进程正常结束（退出码 0）；多行提示词与约 200 KB 的提示词，回显与原文逐字相同；收到 SIGINT 时，回显在中断前已经输出。
• 给了 --image 时，content 换成数组：每张图片一个 image 元素，按给出的顺序排列，最后是提示词的 text 元素。回显里的 text 元素就是提示词原文。

  {"type":"user","message":{"role":"user","content":[
    {"type":"image","source":{"type":"base64","media_type":"image/png","data":"<base64>"}},
    {"type":"text","text":"<提示词>"}
  ]}}

  claude-code 2.1.303 实测：四种类型都能让模型读出图中的文字；48 MB、4000×4000 像素的 PNG 由 claude-code 缩小后交给模型，不报错。

--settings 在沙箱打开、或者不可读列表不为空时传。permissions 只在不可读列表不为空时写，autoMemoryDirectory 与 sandbox 只在沙箱打开时写：

{
  "permissions": {
    "deny": ["Read(//<路径>)", "Read(//<路径>/**)", ...]
  },
  "autoMemoryDirectory": "<会话临时目录>/claude-memory",
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "autoAllowBashIfSandboxed": true,
    "allowUnsandboxedCommands": false,
    "filesystem": {
      "allowWrite": ["<cwd 的绝对路径>", "<会话临时目录>"],
      "denyRead": ["<路径>", ...]
    },
    "network": {
      "allowedDomains": []
    }
  }
}

autoMemoryDirectory 把 auto-memory 目录改到会话临时目录里。理由：claude-code 对当前项目 memory 目录里的 .md 文件内置放行 Write 与 Edit，不看 auto-memory 是否关闭，也不受 dontAsk 与放行规则限制；不改目录时，沙箱打开的运行仍能写用户的 MEMORY.md，内容会进入用户之后的 claude 会话。改到会话临时目录后，写用户的 memory 目录被拒绝（claude 2.1.288 与 2.1.303 云端实测）。沙箱没有运行时 Write 本来就能写任何位置，所以只在沙箱设置里改。

allowWrite 与空的 allowedDomains 生效：Bash 能写 allowWrite 列出的目录，不能写 /tmp 的其他位置，不能联网（云端实测）。failIfUnavailable 不能发现沙箱启动失败：PATH 里的 bwrap 启动失败时，claude-code 不报错，每条 Bash 命令以退出码 1 失败，整次运行仍报告成功（云端实测）。所以沙箱能否使用只靠 agentrun 的启动前检查判断，这一项保留作为额外的保护。--network full|custom 时 network 改为 {"allowedDomains":[],"httpProxyPort":<代理端口>,"socksProxyPort":<代理端口>}，两个端口都是过滤代理的 TCP 端口（过滤代理按第一个字节区分 HTTP 与 SOCKS5）；--dry-run 的命令里端口写成 <proxy port>。deny 与 denyRead 的路径来自读取限制，路径是符号链接时链接与目标都写；不可读列表为空时没有 denyRead。

输出映射

stream-json 每行一个 JSON 对象。用到的对象与字段：

• parent 取所在 assistant 消息的 parent_tool_use_id；它不是任何 subagent_start 的 id 时按 null 处理。
• subagent：kind 取 input 的 subagent_type，缺省为 general-purpose；model 取 input 的 model；description 取 input 的 description 第一行。subagent 默认在后台运行，启动后立即有一个 status 为 async_launched 的 tool_result，这个结果不输出事件。前台运行的 subagent 没有 task_notification，在收到它的 tool_result 时输出 subagent_end，is_error 为 true 时 failed。subagent 交回结果用的内部工具 SubagentHandback 不输出 tool。
• usage：claude-code 把一次模型调用拆成多条 assistant 消息（thinking、tool_use、text 各一条），它们的 message.id 相同，每条都带 usage。同一个 id 只输出一个 usage，取最后一条的值，time 取输出时的时间。合并按 parent_tool_use_id 分别进行：主 agent 与每个 subagent 各保存一条待输出的用量，某个 parent 出现新的 message.id 时输出它自己的那条；输出 subagent_end 之前与运行时结束时输出全部待输出的用量。理由：多个 subagent 并行时，它们的 assistant 消息交错出现，只按 id 的先后判断会把一次调用拆成多个 usage。字段：input_tokens、output_tokens、cache_read_input_tokens、cache_creation_input_tokens；这里没有费用，cost_usd 为 null。model 为 <synthetic> 的消息不输出 usage，它的文字照常输出。
• 一次运行可能有多个 result：subagent 在后台运行时，主 agent 每收到一个 subagent 的结果就多一轮，每轮一个 result，modelUsage 是到当时为止的累计值。所有用到 result 的地方都取运行时退出前的最后一个。end.usage 由它的 modelUsage 按模型换算，costUSD 对应各模型的 cost_usd，总量的 cost_usd 取 total_cost_usd。

失败判定

以下任一成立即为 failed，detail 按顺序取第一项的信息：

1. 最后一个 result 的 is_error 为 true：取它的 result 文字。例如无效模型（同时退出码 1、标准错误有 [claude-code:unrecognized_model]）、无效凭据（退出码 1）。
2. 退出码非 0：取标准错误的最后 500 个字符。例如未知选项，没有任何事件。
3. 退出码 0 但没有 result：runtime exited with code 0 without a result event。

收到 SIGINT 时 claude-code 约 0.4 秒退出，退出码 0，最后的 result 为 is_error: true、subtype error_during_execution；SIGTERM 时退出码 143、没有 result。两种情况都由 agentrun 记为 interrupted。

auto 模式的分类器会拒绝部分命令。实测稳定被拒绝的是读取凭据的命令，例如 cat ~/.ssh/id_rsa；用 curl 把文件外发会触发模型的安全拦截，整次运行以 API Error 失败。

pi

参数

<pi 的绝对路径> -p --mode json
  --no-session | --session-dir <临时目录>/pi-session | --session <临时目录>/pi-session/<文件名>
  --no-extensions --no-skills --no-prompt-templates --no-themes --no-context-files
  --no-approve --offline
  --tools read,bash,edit,write,grep,find,ls
  [--model 服务商/模型] [--thinking LEVEL]
  <-- 之后的调用方参数> [-- @<图片副本>...]

• --no-context-files 不读 AGENTS.md 与 CLAUDE.md；--no-approve 不信任工作目录里的项目级配置，因为工作目录 agent 可写，项目级配置能在 pi 进程内执行代码；--offline 启动时不联网下载资源。
• 提示词原文写入标准输入后关闭，不放在命令行里。理由：pi 把以 @ 开头的位置参数当成文件路径，写在 -- 之后也一样，文件不存在时报 File not found 退出，文件存在时把文件内容当成提示词。pi 去掉标准输入内容首尾的空白（pi 1.0.1 与 1.2.0 相同），所以模型收到的提示词与 prompt 事件都没有首尾的空白与空行，中间的换行与缩进不变；claude-code 与 codex 收到的是原文。调用方参数里的位置参数由 pi 当成消息：第一个直接接在提示词后面，中间不加分隔，之后的每个各算一轮新的消息，以 @ 开头的被当成文件。所以调用方参数里只写选项。
• 给了 --image 时，命令最后加上 -- 与每个图片副本的 @<路径>。pi 按文件内容识别出图片，把它作为图片元素放进用户消息，并在提示词之后为每个文件加一段 <file name="<路径>"></file>；按模型的限制缩小图片时，还在最后追加一行尺寸说明（pi 1.2.0 实测，48 MB、4000×4000 像素的 PNG 被缩小到 2000×2000）。
• --effort 传成 --thinking。--no-subagents 不起作用，也不报错。
• 沙箱打开时，整条命令前面加上包裹命令，见沙箱与网络。Linux：

  bwrap --ro-bind / / --bind <cwd> <cwd> --bind <临时目录> <临时目录>
    --bind <pi 状态目录> <pi 状态目录>
    --ro-bind <状态目录里已有的条目> <同一路径>...
    --bind <auth.json 的链接目标> <同一路径>
    --tmpfs <不可读的目录> --remount-ro <同一路径>...
    --ro-bind /dev/null <不可读的文件>...
    --dev /dev --proc /proc --die-with-parent --unshare-net --
    /bin/sh -c '"$0" "TCP-LISTEN:$1,bind=127.0.0.1,fork,reuseaddr" "UNIX-CONNECT:$2" 2>/dev/null & shift 2; exec "$@"'
    <socat> <代理端口> <临时目录>/proxy.sock
    <pi 的命令>

  macOS 是 /usr/bin/sandbox-exec -f <临时目录>/seatbelt.sb <pi 的命令>。状态目录的三组参数见沙箱与网络：--ro-bind 对目录里除五个可写条目之外的每个已有条目各一组，auth.json 不是符号链接时没有最后一组 --bind；算不出状态目录（PI_CODING_AGENT_DIR 与 HOME 都没有）时这三组都没有，--dry-run 下目录不存在时也没有。不可读的路径见读取限制，不存在的路径没有对应的参数。Linux 的 sh 先在后台启动 socat，把沙箱里 127.0.0.1 上与过滤代理相同的端口号转发到会话临时目录里的 Unix socket，再用 exec 换成 pi，进程组与退出码不变；pi 退出后进程组收到 SIGKILL，socat 一起结束。socat 的标准错误指向 /dev/null：沙箱里的进程中途关闭连接时 socat 会打印一行 read 错误，这些行会混进 pi 的标准错误输出；转发本身不会启动失败，因为命名空间里只有回环接口，socket 文件在启动 pi 之前已经存在。
• 环境里不另设变量。pi 按 PI_CODING_AGENT_DIR、未设时 ~/.pi/agent 使用用户的状态目录，见pi 使用用户的状态目录。

模型检查

--model 必须写成 服务商/模型，可以带 :推理强度 后缀；没有 / 或任一侧为空时是用法错误。理由：pi 对模型名做模糊匹配，能匹配上的未知模型名会被换成别的服务商的模型，退出码仍为 0。例如环境里有 AWS_ 变量时，deepseek/deepseek-v4-flash（1.0.1 已改名为 deepseek-flash）被换成了 Amazon Bedrock 上的模型。

给了 --model 时，agentrun 在第一个 assistant 的 message_start（此时还没有请求模型）比较它的 provider 与 model，区分大小写，不做别名处理。不一致时向进程组发 SIGKILL，判为 failed，detail 为 pi uses <provider>/<model>, which does not match --model <值>。

没给 --model 时不传，pi 用它 settings.json 里的默认模型。设置里的模型不存在、或者没有设置文件时，pi 同样会不提示地改用环境里其他可用的服务商。这种情况由 doctor 的登录检查发现：它报告 pi 实际选中的服务商与模型，与设置不一致时失败。

输出映射

--mode json 每行一个事件，只用以下几种，其余（session、message_update、turn_end、agent_end 等）只写入 --raw。不用 turn_end 与 agent_end，因为它们重复 message_end 的内容，会重复计算用量。

summary：bash 写 command 的第一行；read、write、edit、ls 写 path（ls 没有 path 时写 .），path 是 --cwd 之内的绝对路径时写相对路径，等于 --cwd 时写 .，与 claude-code 的 Read、Edit、Write 相同（display_path）；grep、find 写 pattern；其他只写工具名。end.result 是最后一个 text。

失败判定

以下任一成立即为 failed，detail 按顺序取第一项的信息：

1. 模型检查不通过。
2. 沙箱运行，且标准错误里有包裹命令开头的行（Linux 是 bwrap: ，macOS 是 sandbox-exec: ）、退出码非 0：包裹命令启动失败，detail 为 sandbox failed to start: 加该行去掉这个前缀后的内容。
3. 退出码非 0：取标准错误的最后 500 个字符。
4. 最后一条 assistant 消息的 stopReason 为 error 或 aborted：取 errorMessage 的前 500 个字符，没有时写 stopReason: 值。
5. 退出码 0 但没有 assistant 的 message_end：pi produced no model reply。

codex

参数

<codex 的绝对路径> exec --json --skip-git-repo-check
  --ignore-user-config --ignore-rules -C <cwd>
  [--image <图片副本>]...
  -c default_permissions=agentrun
  -c 'permissions.agentrun.filesystem={":root"="read", ":workspace_roots"={"."="write"}, "<会话临时目录>"="write", "<不可读的路径>"="deny", ...}'
  -c permissions.agentrun.network.enabled=false
  -c approval_policy="never" -c web_search="disabled" -c project_doc_max_bytes=0
  -c skills.include_instructions=false -c skills.bundled.enabled=false -c allow_login_shell=false
  --disable apps --disable plugins --disable remote_plugin --disable plugin_sharing
  --disable tool_suggest --disable hooks --disable skill_mcp_dependency_install
  --disable image_generation --disable goals --disable memories --disable shell_snapshot
  --disable computer_use --disable browser_use --disable browser_use_external
  --disable in_app_browser --disable daemon_auto_start
  [-m ID] [-c model_reasoning_effort="LEVEL"]
  <-- 之后的调用方参数> [resume <会话 id>] -

• 环境里 CODEX_HOME 指向私有目录，见私有配置目录；它不出现在 argv、start.env 与 set: 行里。最后的 - 表示从标准输入读提示词，提示词原文写入标准输入后关闭。
• 沙箱打开时用名为 agentrun 的自定义权限配置，会话临时目录写真实路径（macOS 上 /var 指向 /private/var）。filesystem 表最后给不可读列表里每个存在的路径加一项 "<真实路径>"="deny"，见读取限制。权限参数的三行按沙箱与 --network 取值如下，web_search 只在 full 下为 "live"：

• 写进 -c 值的字符串按 TOML 基本字符串写：外加双引号，\ 写成 \\，" 写成 \"，控制字符写成 \uXXXX。用于会话临时目录路径、--effort 的值与主机名。
• --dry-run 时会话临时目录写成 <tempdir>，私有目录写成 <tempdir>-codex（只在环境里，不在 argv 里）。
• 登录文件的检查与私有目录的创建由 Codex::launch 做。用户登录文件（$CODEX_HOME/auth.json，未设时为 ~/.codex/auth.json）不存在、也没有给出 AGENTRUN_CODEX_AUTH 时启动前报错，--dry-run 也检查，detail 为 codex login file <路径> not found. Run codex login, or pass its content in AGENTRUN_CODEX_AUTH。私有目录创建失败的 detail 为 cannot create the codex home directory <路径>: <系统错误>。
• 不加 --ephemeral：加了以后 subagent 无法启动（报 no rollout found for thread id，codex 0.159.2 实测）。会话记录写进私有目录，随它一起删除；给出 --session-dir 时先移到 DIR/codex/，见保存与继续会话。resume 子命令没有自己的 -C，写在它前面的 -C、-c、--disable、-m 照常生效（0.159.2 与 0.163.0 实测）。
• --disable 列表关闭会给模型增加工具或在 codex 进程里执行用户代码的功能。shell_snapshot 与 allow_login_shell=false 让命令不读用户的 shell 配置。其中 computer_use、browser_use、daemon_auto_start 等在 exec 下没有可见效果，仍然关闭。功能名不存在时 codex 报错退出，所以这份列表要随 codex 版本核对。
• --no-subagents 加 -c agents.enabled=false --disable multi_agent --disable multi_agent_v2。只关 multi_agent 不够，模型目录里的设置优先（codex 0.159.2 源码）。
• --max-turns 与 --max-tokens 是用法错误，见轮数与 token 上限。
• --deny-read 的真实路径含 * ? [ ] { } 时是用法错误，见读取限制。
• 给了 --image 时，每个图片副本一组 --image <路径>，紧跟在 -C <cwd> 之后（codex 0.160.1 实测 PNG、JPEG、GIF、WebP 与多张图片）。codex 的 --image 接受一个或多个值，并把逗号当作值之间的分隔符（codex 源码 codex-rs/utils/cli/src/shared_options.rs），所以它后面必须紧跟另一个选项，否则最后的 - 会被当成图片；路径里有逗号时 codex 会把它拆成两个文件，这时启动前报错，detail 为 cannot give images to codex: the path <路径> contains ',', which codex reads as a list separator。副本路径在会话临时目录里，只有 $TMPDIR 含逗号时才会出现这个错误。

输出映射

denied 恒为 false。codex 的输出里没有 subagent 的启动事件，也没有 subagent 自己的命令与文件改动，只有主 agent 等待 subagent 的 collab_tool_call（tool 为 wait，codex 0.159.2 实测）。所以 codex 不输出 subagent_start 与 subagent_end，parent 全部为 null。

失败判定

1. Linux 上沙箱运行时，有 item.completed 里 command_execution 的 aggregated_output 以 bwrap: 开头：detail 为 sandbox failed to start: 加这一行去掉 bwrap: 的部分，有多条时取第一条。启动前检查已经覆盖已知的失败情况，这一条是附加信号：codex 的沙箱启动失败时仍以退出码 0 结束并输出 turn.completed，只有命令的输出里有 bwrap 的报错；模型改用 file_change 写文件时连这条报错也没有（codex 0.160.0 实测）。
2. turn.failed：取最后一个的 error.message 前 500 个字符。
3. 没有 turn.completed 时的 error 事件：取最后一个的 message 前 500 个字符。codex 重试连接时也输出 error，重试成功后照常完成，所以有 turn.completed 时不看 error。
4. 退出码非 0：取标准错误的最后 500 个字符。
5. 退出码 0 但没有 turn.completed：codex produced no turn.completed。

dsh

参数

<dsh 的绝对路径> headless --patch <临时目录>/dsh-patch.yml --json
  [--session-id session-<会话 id>]
  <-- 之后的调用方参数> -

• headless 是 dsh 的非交互 profile，--json 让它每行输出一个事件，最后的 - 表示从标准输入读任务；提示词原文写入标准输入后关闭。--patch 是 dsh 启动器的选项，必须写在 --json 之前，写在后面时 dsh 报 unknown option '--patch'。提示词不放在命令行里，理由：以 - 开头的位置参数被 dsh 当成选项，dsh 也不接受 --（0.2.1-rc.2 实测）。调用方参数写在 --json 之后、- 之前，只写 headless 的选项。
• 环境里 DSH_HOME 指向会话临时目录里的 dsh-home/，DSH_AGENTS_HOME 指向空目录 dsh-agents/，两个目录在启动前创建，权限 0700；另设 DSH_PERMISSION_MODE=danger-full-access 与 DSH_TELEMETRY_DISABLED=1。这四个变量在 --env 之后设置，调用方不能用 --env 改回。调用方环境里以 DSH_ 开头的变量启动前删除，见会话环境；私有目录关掉了哪些配置来源，见配置与账号。
• DSH_PERMISSION_MODE=danger-full-access 关掉 dsh 自带的沙箱与审批，写限制只由 agentrun 的包裹执行；沙箱没有运行时同样这样设置，与 codex 在沙箱没有运行时用 :danger-full-access 一致（用户定）。理由：dsh 自带的沙箱只限制写文件，不限制网络；默认的 workspace-write 下 bash 命令的 /tmp 在命令结束后消失，需要审批的操作在 headless 里没有人回答，直接失败；macOS 上 dsh 在 agentrun 的 Seatbelt 里用 workspace-write 时每条 bash 命令都报 no sandbox backend is usable on this host（0.2.1-rc.2 在云端与 macOS 实测）。
• 会话环境里必须有非空的 DEEPSEEK_API_KEY，没有时启动前拒绝，--dry-run 也检查，detail 为 DEEPSEEK_API_KEY is not set in the session environment. Export it, or pass it with --env DEEPSEEK_API_KEY=<key>。理由：会话环境没有这个变量时，dsh 读工作目录里 .env 的 key，agent 能写工作目录，下一次运行的账号就由 agent 决定；私有 DSH_HOME 里没有用户的 ~/.dsh/.env（用户定）。DEEPSEEK_BASE_URL 照常进入会话，dsh 用它访问兼容的模型服务。
• 补丁文件 dsh-patch.yml 写在会话临时目录里，权限 0600，内容是一个 JSON 数组，dsh 按 YAML 读它。每一项按 id 修改 dsh 的一个配置条目。始终关闭的七个条目：

  条目	关闭的内容
  agent-instructions	读 AGENTS.md、CLAUDE.md 等指令文件
  skill-filesystem	读用户与项目的技能目录
  session-log-deepseek	每次模型请求在请求体里附带会话事件（dsh_session_log）
  plugin-package-inventory-deepseek	请求体里附带已安装插件的清单
  session-telemetry-otel	OTel 遥测导出
  session-title-llm	额外请求一次模型生成会话标题。这次请求的用量不出现在输出里
  tool-web	web_search 与 web_fetch 两个工具（用户定）。理由：web_search 由模型服务执行，请求只到 api.deepseek.com，过滤代理无法按主机限制它，--network none 也拦不住

  给了 --no-subagents 时另外关闭 tool-subagent、tool-subagent-fork、tool-workflow、tool-subagent-control、tool-subagent-list-agents，模型的工具列表里随之没有 subagent、workflow 与给 subagent 发消息的工具（实测）。给了 --model ID 时加 {"id":"agent-default-model","config":{"provider":"deepseek-official","model":"ID"}}，模型名不检查，不存在的模型在第一次请求时报 INVALID_REQUEST；没给时用 dsh 的默认模型。给了 --effort LEVEL 时加 {"id":"llm-deepseek","config":{"reasoningEffort":"LEVEL"}}，dsh 接受 off、low、high、max，其他值在联网前报 UNSUPPORTED_REASONING_EFFORT。
• 补丁按 id 匹配条目，dsh 把某个条目改名或删除后，这一项既不报错也不生效。升级 dsh 后用 dsh headless --patch <补丁文件> --dump-config 核对合成后的配置，它不发请求。
• --image 是用法错误，detail 见图片。
• 沙箱打开时，整条命令前面加上包裹命令，与 pi 相同，只是没有 pi 状态目录的三组参数：Linux 是 bwrap 加 socat，macOS 是 sandbox-exec 与会话临时目录里的 seatbelt.sb。dsh-home/ 与 dsh-agents/ 在会话临时目录里，所以 dsh 能写它们。被 bwrap 包裹时第一个信号直接发给 dsh，与 pi 相同，见进程、信号与超时。

这段输出取自 Cloud Managed 容器，工作目录、dsh 的路径与 PATH 改成了短路径。agentrun 设置的四个 DSH_ 变量不出现在 set: 一行与 start 事件的 env 字段里。

输出映射

--json 每行一个事件。字符串字段超过 8 KiB 时被 dsh 截断，final 不截断。

summary：bash 写 command 的第一行；read、write、edit、read_image 写 file_path，在 --cwd 之内时写相对路径，等于 --cwd 时写 .，与 claude-code、pi 相同；glob、grep 写 pattern；其他只写工具名。

dsh 只输出主会话的事件。subagent 里的工具调用不出现，主会话启动 subagent 的调用照常输出 tool_start 与 tool，所以 dsh 不输出 subagent_start 与 subagent_end，parent 全部为 null。

这段输出取自 Cloud Managed 容器，工作目录改成了短路径。dsh 不报告费用，[end] 行没有金额。

失败判定

以下任一成立即为 failed，detail 按顺序取第一项的信息：

1. 有 error 事件：取它的 message 前 500 个字符。dsh 启动阶段的错误只有这个事件，例如未知选项与空任务。
2. turn_end 的 reason.kind 为 error：取 reason.error 的 code: message 前 500 个字符，没有 message 时只写 code。kind 是 completed 以外的其他值（max-tokens、aborted、interrupted）时写 turn_end reason: 值。
3. 退出码非 0：与 pi 相同，先看包裹命令是否启动失败，再取标准错误的最后 500 个字符。
4. 退出码 0 但没有 turn_end：dsh produced no turn_end。

SIGTERM 后退出码为 0，所以中断只按 agentrun 自己收到的信号判定，见进程、信号与超时；超过上限被停止的运行因为没有 turn_end，按上面的第 4 条不满足 finished，结果是 limit，见轮数与 token 上限。dsh 在新的进程组里启动命令，这些命令由 agentrun 的进程树清理结束（云端实测 SIGINT 与 SIGTERM 后没有留下进程）。本机 Linux 上用户的 systemd 可用时，dsh 改用 systemd-run --user --scope 启动命令（dsh 源码），这种情况没有实测。