sub-agents · diff
git:20261009.1d9b63e to git:20261010.d51765b
83 added, 295 removed. Audit A to A.
---
name: sub-agents
- description: "通过 claude-agent-run 或 codex-agent-run 子进程启动外部子 Agent。用于隔离或并发派发调查、实现和 review 任务,并检查进程与结构化输出。"
+ description: "通过 claude-agent-run 或 codex-agent-run 启动外部子 Agent,派发独立或并行任务,等待退出并取得最终答复。需要时可选用 canary、产物检查及 macOS 禁读隔离。"
---
# Sub Agents
- 使用下述 runner 子进程派发子 Agent。此 skill 激活时,所有子 Agent 调用都必须遵循本协议。
-
- ## Runners
-
- | Runtime | Command | Providers | Default structured output |
- | --- | --- | --- | --- |
- | Claude Code | `claude-agent-run` | `ds-flash mimo mimo-fast mimo-flash qwen kimi glm glm-flash local hy` | one JSON result |
- | Codex | `codex-agent-run` | `ds-flash mimo mimo-fast mimo-flash qwen kimi glm glm-flash local gpt-6-astra gpt-6-sol gpt-6-luna business` | JSONL event stream |
-
- 两个 runner 已在 PATH,直接以命令名调用。调用前先跑 `<runner> --help` 确认可用与接口,并用 `pwd -P` 得到当前任务
- workspace 的绝对路径。每次调用必须显式传入 `--cwd "<absolute-workspace>"`,不得依赖总控当前目录。
-
- codex 的 runner 按 `--cwd` 自动判定并追加 `--skip-git-repo-check`(非 git 仓库时),无需手工传;claude-agent-run 无此参数。
-
- ## Preflight Checklist
-
- 每次派发前逐项过。`sub-agent-preflight` 只完成可机械验证的 setup / 结构检查,生成 run_dir / canary /
- 最终 prompt(任务正文 + 本轮固定报告协议),并打印命令。它只能拒绝可识别的字面值、路径、
- provider 形式 token 和固定协议标记,不能靠正则证明任意自然语言同义旧报告指令不存在。总控仍须逐项核对
- 下方 Dispatch Contract、prompt 的语义完整性、实际授权和并发写边界;尤其要按语义拒绝任何与本轮报告协议
- 冲突的旧报告动作。`setup_status=ok` 不证明这些内容正确:
-
- ```bash
- sub-agent-preflight --runtime <claude|codex> --provider <name> --cwd "<absolute-workspace>" --label "<unique-label>" --task-file <path>
- ```
-
- `setup_status=ok` 才可派发;任何 `failure=` 都是 **controller setup error**(见失败分类),修好后重跑,不得带着
- setup 错误派发。
-
- 只有 `sub-agent-preflight` 不可用(未安装或执行失败)时才允许手工预检:必须逐项完成同样八项,把每项结果写进
- 报告(`setup_status` + 逐条 `failure`),不得跳过检查直接派发:
-
- - [ ] workspace 用 `pwd -P` 解析为绝对路径,`--cwd` 显式传入,不依赖总控当前目录;
- - [ ] Git 条件已判定(`git -C "$workspace" rev-parse --is-inside-work-tree`);codex 的非仓库情形由 runner 自动处理;
- - [ ] 两个 runner 均在 PATH,且各自的 `--list-providers` 成功并包含完整基线;`<provider>` 出现在所选 runner 的
- catalog(预检用另一 runtime 的 catalog 识别跨 runtime 旧 token);
- - [ ] launcher 函数与 profile 已部署(codex `business`:`~/.codex-agent/business/config.toml`;其它 Codex
- provider:`~/.codex/<provider>.config.toml`;与 `scripts/agent-tools.zsh` 的 home / `-p` 解析一致);
- - [ ] prompt 是完整任务正文(`--task` / `--task-file`,或 `--prompt-file` 给完整正文;预检均生成本轮最终副本并追加报告协议),
- 含 `目标` / `非目标` / `停止条件` 三节(每节单独一行、行首写节名,英文 `Goal` / `Non-goals` / `Stop condition`
- 等价;预检会校验)。三种来源均不得含旧 `CANARY=` / `CANARY:` 值、`canary.txt` / `canary.expected`
- 文件名(包括裸文件名或路径)、provider 形式的裸旧 token、或固定报告指令;普通讨论 CANARY 概念可以保留。
- 预检会在追加本轮协议前检查机械特征;总控还须语义检查其它旧报告动作,确保追加的本轮协议为准;
- - [ ] 输出路径(`--output` / `--stderr` / `--last-message`)全新,label / `--instance` 唯一;
- - [ ] 一次性任务用 `--no-persist`;默认权限不变;显式隔离派发见下节;
- - [ ] 并发无写冲突:写入范围重叠或有依赖时必须串行。
-
- ## Dispatch Contract
-
- runner 收到的 `--prompt` / `--prompt-file` 在新的独立 Agent 上下文执行;它不继承总控对话、裁决或用户授权。
- 相同 `--cwd` 只确定工作目录,同一文件系统或相同 provider 也不传递这些上下文。总控须在任务 prompt 中交接
- 本任务必要的背景、已决事项及其依据、用户授权范围、冻结输入版本、依赖和验收信号;也可给出明确可定位的
- 文件路径及版本供子 Agent 读取。只交接本任务必要信息,不转发无关的对话全历史或敏感信息。
- 不得使用只有父上下文知道意义的“刚才”“照旧”“已确认”等引用。必要信息缺失、不可访问或版本不符时,
- 子 Agent 应报告 `blocked` 和缺项,不得猜测。
-
- 每个子 Agent 的 prompt 必须明确:
-
- - 目标、非目标和 stop condition;
- - 本任务所需的既有决定、授权边界、输入 artifact 与冻结身份(适用的 HEAD/base/hash/版本)以及关键依赖;
- 不适用项明确写 `N/A`,不得把 `--cwd` 或工具权限当作用户授权;
- - 探针 / 验证类任务的非目标必须包含"不得再派发子 Agent"(任务本身是编排时除外);
- - 可读取、可修改以及禁止修改的文件;
- - 是否允许调用工具和允许的副作用;
- - 相关代码、文档和约束的路径;
- - 预期输出格式、artifact 路径、validation、可验证的成功判据与必要证据;
- - 报告开头必须声明自身的 runtime、provider 和 model;自报与 event stream 不符时以 event stream 为准;
- - 禁止 commit、push、PR、merge 或进入其它 gate,除非任务明确授权。
-
- 一次性任务默认使用 `--no-persist`。Claude 调用必须使用唯一 `--instance`。Codex runner 没有
- `--instance` 参数,应使用唯一 task label、输出文件名,并把该 label 写入 prompt。
-
- 子 Agent 权限默认继承 auto 模式,无需显式传 `--permission-mode`;需要收紧时显式指定。Codex 用 `--sandbox`
- 选择内层沙箱级别。单独的 `--full-access` 关闭内层沙箱与工具审批,不提供输入隔离;只在调用方明确选择
- 这种权限时使用。不得通过宽权限扩张用户授权或任务 scope。
-
- ## Execution And Isolation
-
- 为每轮派发创建独立目录:
-
- ```bash
- run_dir="$(mktemp -d "${TMPDIR:-/tmp}/sub-agents.XXXXXX")"
- workspace="$(pwd -P)"
- ```
-
- 默认调用:
-
- ```bash
- claude-agent-run \
- --provider ds-flash \
- --cwd "$workspace" \
- --instance "review-dsflash-01" \
- --no-persist \
- --output-format json \
- --output "$run_dir/review-dsflash-01.json" \
- --stderr "$run_dir/review-dsflash-01.stderr" \
- --prompt "<bounded task>"
-
- codex-agent-run \
- --provider gpt-6-astra \
- --cwd "$workspace" \
- --no-persist \
- --output-format json \
- --output "$run_dir/review-astra-01.jsonl" \
- --stderr "$run_dir/review-astra-01.stderr" \
- --last-message "$run_dir/review-astra-01.last.md" \
- --prompt "<bounded task>"
- ```
-
- 派发必须在沙箱外运行,方式取决于总控环境:
-
- - Claude 总控:以独立的一次 Bash 调用发出——裸命令、无引号、无 `$HOME` 前缀、不管道、不复合,run_dir 等准备
- 工作在之前的调用完成,使命令命中 `excludedCommands`;
- - Codex 总控:每个子 Agent 使用一次独立的 `exec_command` 调用,显式设置 `sandbox_permissions:
- "require_escalated"`(附 justification);若返回 session_id,通过对应的 `write_stdin` 收集。
-
- 沙箱内派发的典型症状:codex 子 Agent 初始化失败(`failed to initialize in-process app-server client`);
- claude 子 Agent 能启动但自身 Bash 不可用(`EPERM ... srt-mux`)。出现这些症状时优先检查派发是否仍在沙箱内;
- 若派发已显式提权,则检查子进程自身的沙箱配置——该报错不唯一指向父级派发未出沙箱。
-
- 并发派发 = 多次**独立**调用(Claude 总控:多次 `run_in_background: true`;Codex 总控:每个子 Agent 一次独立的
- `exec_command`,若返回 session_id 则用对应的 `write_stdin` 收集)。Claude 环境中复合命令(`&`、`&&`、管道)
- 可能无法命中 `excludedCommands`,导致子 Agent 的 Bash 失效。
- 收集时逐个核对各自退出码与 artifact。存在数据依赖、
- 写入顺序依赖或 file ownership 重叠时必须串行。不得让多个子 Agent 并发修改同一文件,除非已划分互不重叠的写入范围。
+ 通过 runner 子进程调用外部 Claude Code / Codex 子 Agent。普通任务直接派发,等待实际退出,读取汇总里的
+ 最终答复,并按任务需要使用或核对成果。项目明确要求的审核、取证和工作流规则仍然适用。
- 不要仅因运行时间长而 kill、重派或切换 provider。后台任务仍在运行、或输出文件仍有变化时,默认仍为 in-flight;
- 判活不得依赖 ps / pgrep / kill -0 等进程查询。只有托管调用句柄返回、进程退出或用户停止等证据,
- 才能认定该进程已结束;文件暂时没有变化不等于进程已退出。Agent 报告无法继续、托管工具明确报告阻塞,
- 或预先约定的超时条件触发时,可标记任务 `blocked`;仍在运行的进程须继续收集或经用户授权停止,
- 不得把 `blocked` 冒充进程已退出。用户明确停止并完成中止后,记录为 `blocked` 与停止原因。
+ ## 直接调用
- ### 可选的任务禁读边界(macOS)
+ | Runtime | Runner | Providers |
+ | --- | --- | --- |
+ | Claude Code | `claude-agent-run` | `ds-flash mimo mimo-fast mimo-flash qwen kimi glm glm-flash local hy` |
+ | Codex | `codex-agent-run` | `ds-flash mimo mimo-fast mimo-flash qwen kimi glm glm-flash local gpt-6-astra gpt-6-sol gpt-6-luna business` |
- 默认调用没有任务级读取隔离。调用方需要禁止读取指定材料时,先备齐本次输入,创建 JSON 数组文件,
- 其中每项为禁止读取的文件或目录的绝对路径;目录递归禁止。路径必须为已存在的普通文件或目录,按字面值处理,不是 glob。
- 调用方决定范围:业务报告、历史日志及已知副本分别列出;封装不推断角色、业务规则或内容相同的未知副本。
+ 每次显式传 `--cwd` 的 workspace 绝对路径,避免依赖总控当前目录。接口不熟悉时查看所选 runner 的 `--help` / `--list-providers`。
```bash
- sub-agent-preflight --runtime codex --provider mimo --cwd /absolute/workspace \
- --label unique-review --task-file /absolute/task.md --deny-list /absolute/denied.json
+ codex-agent-run --provider mimo --cwd /absolute/workspace --prompt-file /absolute/task.md
+ claude-agent-run --provider ds-flash --cwd /absolute/workspace --prompt "检查 src/parser.py 对空输入的处理,只报告发现,不修改文件。"
```
- 预检生成 `agent-sandbox ... -- codex-agent-run ... --full-access ...` 命令;Claude 同样通过对应 runner。
- 也可显式用 `agent-sandbox --cwd /absolute/workspace --deny-list /absolute/denied.json -- <runner> ...`。
- 封装隐含 `--full-access --no-persist`,固定本次文件系统策略。它不支持 resume、native 参数透传、stdin prompt、动态投递或追加 prompt。必须恰好一个非空 `--prompt` 或普通
- `--prompt-file`,启动前复制到受写保护的状态;随后关闭 stdin。
- `--cwd` 只决定工作目录;获准来源、Python 依赖和 canary 仍可按原路径读取,禁读名单之外没有读取白名单。
- 启动后在外层 Seatbelt 内验证禁读路径确实被拒绝,再启动 Agent;setup 通过本身不是隔离证据。
-
- 封装必须从总控沙箱外启动:Codex 总控仍使用独立 `exec_command(require_escalated)`;Claude 总控须将
- `agent-sandbox` 加入自己的 `sandbox.excludedCommands`,并以独立裸命令派发。内层 Full Access 无法解除
- 外层 Seatbelt。保留原有生命周期、canary 和结果验收协议;权限错误应报告具体缺项,不自动移除禁读项或放宽权限。
-
- 首次使用前,由用户按仓库 README 安装可选 srt 依赖。封装只支持经测试的 macOS/srt 版本,检查失败立即停止。
- 大名单通过策略文件加载,同一禁令的路径条件仅做等价压缩;仍须逐项通过内核禁读验证。
- 策略原路径禁止写入/移动,但硬链接别名可能改写留存文件,不影响已加载的内核策略。
- 总控须通过可信父进程 pipe 收集封装 stderr 中 runner 启动前第一条 seatbelt_profile= 适配器记录的
- profile_sha256/source_sha256;后续重复行可能由子进程伪造,不得覆盖首条或采用 last-wins 解析。
- 使用留存策略作证据前比对哈希,不可信任 Agent 可修改的日志或仅凭留存文件。
- stderr 中的 state/seatbelt_profile 可定位保留的策略证据。启动参数超限或原生策略编译失败属于封装启动失败,
- runner 尚未启动,不能算 provider 已执行任务;向调用方报告原始错误,不删减禁读项、跳过验证或退回普通派发。
- 它保留原 runtime 写范围的保守子集及指定输出文件,复制并保护 Codex 用户 `.rules`;不能推导的自定义权限配置会拒绝启动。隔离调用不加载
- 宿主 MCP、hooks、plugins 或浏览器工具;Claude 仅启用 Bash/Read/Write/Edit/Glob/Grep,Codex 使用本地原生工具。
- 禁读路径在运行期间不得由其它未隔离进程替换或复制;已有硬链接会拒绝启动。需要的工具/网络缺项须报给调用方裁定。必需的凭据/配置文件列入禁读时 setup 会停止;不提供凭据与 Agent 工具之间的隔离。
-
- ### Sandbox Process Management
-
- 沙箱(`sandbox.enabled`)下进程管理一律使用下列配套方法,不要在协议里使用 `ps` / `pgrep` 或其它进程列表工具。
-
- - **派发与收集(Claude 总控)**:用 Bash 工具的 `run_in_background: true` 独立发出;harness 托管的后台任务跨调用
- 存活,通过后台任务句柄收集完成状态与退出码,输出由 harness 落盘。不要用 shell `&`——其子进程在沙箱下会随
- Bash 调用结束被回收;
- - **派发与收集(Codex 总控)**:每个子 Agent 一次独立的 `exec_command`;可能直接返回退出码,也可能返回 session_id,
- 后者用 `write_stdin` 持续收集,直到取得退出码;
- - **进度判据**:run_dir 内输出文件(或后台任务的 harness 输出文件)的大小 / mtime 变化,不要用进程列表;
- - **退出码**:Claude 后台取托管任务完成通知,Codex 取 `exec_command` / `write_stdin` 返回的退出码;
- 前台直接调用取其返回码。仅在对应 harness 明确提供时使用完成通知中的退出标记,不假设 runner 输出文件自带该标记;
- - **输出流**:后台模式会把 stdout/stderr 合并进同一文件,因此结构化输出与日志必须继续通过 `--output` /
- `--stderr` 落到 run_dir。
-
- ## Result Validation
-
- 分开裁定**派发生命周期**和**结果可信度**。沙箱内以 Sandbox Process Management 一节所述句柄收集退出状态:Claude 后台任务的完成通知,
- Codex `exec_command` 的退出码或 `session_id` 后续 `write_stdin` 的退出码;前台调用则取其直接返回的退出码。
- 不得以 `ps` / `pgrep`、文件大小或最终消息代替退出证据。进程结束后检查 exit code、stderr、取得的全部结构化输出、
- 最终消息及要求的 artifact;结构化终态与外层退出码都要核对。任一仍在途时不作最终验收。
-
- 任务要求工具调用时,"完成"不证明实际执行过工具;需有可核对的工具执行记录。它只证明调用发生,
- 不证明每项必需取证都成功,后者还须按任务要求核对:
-
- - Codex:event stream 中有实际 `command_execution` 或 `mcp_tool_call` 的结果;命令非零退出也可能是有效反例,
- 但必须按下文检查影响;
- - Claude:`num_turns >= 2` 只表明多轮交互;canary 匹配只证明指定文件读取成功,不能证明其它工具调用成功。
-
- 验证类派发(探针、验收、产出会被下游信任)必须使用 canary:
-
- 1. `TOKEN="<prefix>-$(openssl rand -hex 4)"`,用 `printf '%s' "$TOKEN" > canary.txt` 写入 run_dir 内文件
- (**不带尾换行**,消除"逐字比较"在结尾空白上的歧义);总控侧另存一份字节相同的 `canary.expected` 作为比对基准;
- 2. prompt 只给文件路径,不得包含 TOKEN 本身(`sub-agent-preflight` 会自检并拒绝含 token 的 prompt);
- 3. 比对规则:子 Agent 报告的 token 字符串与基准**逐字一致**(仅边缘空白不计);需要字节级证据时,直接比对子 Agent
- `cat canary.txt` 的原始输出与文件字节。不等即判失败——即使其它检查全部通过。
-
- 伪造型静默失败是硬失败,不重试,记录并上报:最终消息含字面工具调用语法(`<tool_call>`、`<tool_result>`、
- 裸 JSON 工具对象)而 event stream 无对应执行事件——provider 级缺陷特征。
-
- 已确认的非致命诊断记录为 warning。下表只给这些诊断的精确识别方式,不做近似匹配;检查位置按表,不看其它流:
+ runner 自动检查所选 provider、workspace、任务输入、launcher 及输出路径;非 Git workspace 的 Codex 自动追加
+ `--skip-git-repo-check`。默认一次性运行,不持久化 session。默认自动分配私有日志目录和 Claude instance;
+ 调用方无需提供 label、instance、日志路径或单独运行预检。需要指定日志位置时使用 `--output` / `--stderr` /
+ Codex `--last-message`,这些必须是新文件;显式 `-` 仅用于 `--detail`,汇总模式明确拒绝。
- | predicate(精确判据) | 检查位置 | 处理 |
- | --- | --- | --- |
- | stderr 某行以 `[claude-code:unrecognized_model]` 开头(其后 JSON payload 不参与匹配) | Claude 侧 stderr | 记录 warning,不判失败 |
- | `item.type == "error"` 且其 message 匹配 `^Model metadata for \S+ not found` | Codex event stream(stderr 不作为豁免依据) | 记录 warning,不判失败 |
- | `item.type == "error"` 且其 message 含子串 `unrecognized_model` | Codex event stream(stderr 不作为豁免依据) | 记录 warning,不判失败 |
+ ## 独立上下文交接
- 除 turn 级终态外,其它 `error` / `failed` 事件及 `command_execution` 的每个非零 `exit_code` 都不得忽略,
- 也**不自动判整次派发失败**。即使 item 外层状态为 `completed`,也要检查命令退出码。总控逐条查看事件对应的命令、错误、任务目的、
- 后续恢复和最终结论:
+ `--prompt` / `--prompt-file` 的任务在新的独立 Agent 上下文执行,不继承总控的对话、裁决或用户授权。
+ 相同 cwd 或 provider 也不传递上下文;runtime 自身可能加载 workspace 的 AGENTS.md 等本地指令和配置。
- - 探索性无匹配、预期的反例或已成功改用其它证据的失败,可以记录为已解释的 warning;例如 `rg` 无匹配本身
- 不证明审核失败。必须说明该失败为何不影响结论,不能只凭 Agent 最终消息未提失败就认定无影响。
- - 测试失败、冻结 diff 比对不一致、读取关键来源失败或工具内核崩溃,先判断该步骤对任务的作用。若它揭示了
- 被审核对象的问题,可保留为有效 finding;若关键取证未恢复,相关结论不得采纳,也不得把缺口写成通过。
- - 审核输入身份校验失败(如冻结 diff 比对不一致)时,先查明并恢复输入身份;未恢复前,针对该冻结输入的
- 审核不能记为 `accepted`。若无法确定失败是否影响必要证据,标记未解决并停在当前 gate;
- 先裁定影响与失败类别,再按 Retry And Sessions 决定是否可重派,不得用重派抹去可评分的错误结论。
+ 用自然语言提供这项任务需要的背景、已决事项、授权、输入/版本、依赖、可写范围和交付要求,或给出可定位的文件路径。
+ 复杂任务明确范围和完成信号;简单任务无需固定标题或填写 N/A。不要使用只有父上下文知道含义的“刚才”“照旧”。
+ 不要求子 Agent 自报 runtime/provider/model。只交接必要信息,不转发无关的历史或敏感信息。
+ 缺少必要输入、授权或工具时应报告具体缺项,不能猜测或自动扩大权限。
- runner / 托管调用的**外层进程**退出非零、缺少可信终态、结构化输出损坏、canary 不匹配、伪造型静默失败
- 仍是硬性拒收条件;`command_execution.exit_code` 非零按上文逐项裁决,不等于外层进程失败。关键 artifact 缺失、
- 无法证明审核了指定输入、未恢复的关键工具失败是结果验收失败。即使派发生命周期正常结束,也须由总控独立核对
- 关键代码、来源、测试或其它任务证据,再决定采纳、部分采纳或驳回;子 Agent 的 final answer 不单独构成验收。
+ 要求交付文件时,把目的及文件路径告诉子 Agent,并要求在最终答复给出产物路径和未完成事项。
+ 修改既有源码无需另写一份报告描述修改;调用方可直接查看源码和任务要求的验证。
- Claude JSON:
+ ## 托管执行与等待
- - 文件必须是有效 JSON;
- - 检查外层 `subtype`、`is_error` 和 `result`;
- - 非成功 subtype、`is_error=true`、缺少 result 或非零退出码均不得判定成功;
- - `result` 可能包含 Markdown code fence。解析其中的 JSON 时先去除 fence,再进行结构化解析。
+ 派发从总控沙箱外运行,避免父级沙箱妨碍 runtime 初始化或子 Agent 的工具:
- Codex JSONL:
+ - Codex 总控:每个任务用一次独立的 `exec_command`,设置 `sandbox_permissions: "require_escalated"` 并说明任务。
+ 返回 session_id 时,用对应 `write_stdin` 收集,直到取得退出码。
+ - Claude 总控:以独立裸 runner 命令调用 Bash,使其命中 `sandbox.excludedCommands`;准备工作在之前完成。
+ 后台运行用 `run_in_background: true`,用托管任务句柄/完成通知收集。不要用 shell `&`、管道或复合命令派发。
- - 每个非空行都必须是有效 JSON event;
- - 检查每个 error / failed event、每条 `command_execution` 的非零 `exit_code` 及其后续处理;
- 要求存在明确的 `turn.completed`。`turn.failed` 或缺少 completion evidence 属派发失败,item 级工具失败按上述影响判定;
- - 优先使用 `--last-message` 保存最终消息,但仍必须同时审查完整 event stream 和 stderr。
+ 并行任务各有独立托管调用和日志。可读输入可以共享;写范围重叠或有数据依赖时串行,或先明确互不重叠的 ownership。
- Claude 默认 JSON 只有汇总结果,无法逐条观察中间工具失败。记录此可见性限制;不能凭 JSON 成功或 canary 匹配
- 断言中间调用均成功。总控须独立复核关键输入、产物及任务所要求的测试或取证;无法复核时,相关结论不能记为
- `accepted`。只有实际取得逐调用轨迹时,才要求逐条列出 Claude 的中间失败事件。
- 空 stderr 不证明成功,非空 stderr 也不自动证明失败;结合退出码、结构化状态及任务证据裁决。
+ 不要仅因耗时长就 kill、重派或换 provider。使用托管句柄判断完成;日志大小/mtime 可用于观察进度,
+ 不能代替退出码;不依赖 `ps` / `pgrep` 等进程查询。在途时继续收集,停止在途 Agent 必须取得用户授权。
+ 任务 blocked 不等于进程已经退出;用户授权中止后保留停止原因。最终消息已出现也不能提前认定进程完成。
- ## Retry And Sessions
+ 沙箱内启动的常见症状是 Codex 初始化失败或 Claude Bash 的 EPERM;先核查父级派发环境,
+ 已提权仍失败时核查 runtime 自身配置,不按单一报错猜根因。
- 失败先归类,再决定动作:
+ ## 取得和使用结果
- - **controller setup error**(派发前失败,子 Agent 根本没跑起来):prompt 文件缺失或为空、`--cwd` 不存在、git 条件
- 处理错、输出路径已存在、runner / launcher / profile 未部署、prompt 含 canary token。**不计入 provider 重试额度,
- 也不计入任何测量批次**;修好后用**新 label** 重派(同修复性重试规则),并在报告里单列为 setup 失败。
- - **provider / 测量失败**(子 Agent 真的运行过):按下方规则处理。
+ 默认在实际 runtime 退出后,runner stdout 返回一个 JSON 汇总;即使指定日志文件也会返回汇总。
+ Claude 原始 stream-json、Codex JSONL 和 stderr 保留,路径在 `logs` 中。Codex 最终答复也在 JSONL 中;
+ 只有显式 `--last-message` 才另存最终消息文件并返回 `logs.last_message`,默认该字段为 null。
- 派发或结果验收失败后,先根据 stderr、结构化输出和任务证据区分配置错误、超时、模型错误或任务错误。
- 裁决块中 `retry_class=provider` 用于 provider / 运行环境故障,`task` 用于 Agent 的命令、取证或任务执行错误;
- 尚未查清原因写 `unknown` 并停在当前 gate,不据此切换 provider。
- 普通工具失败已恢复且不影响结论时,不消耗重试额度。确需重派时只允许一次有明确理由的同 provider 重试;
- 再次失败后,若任务或项目另有替补路由限制,先遵从该限制;否则可切换 provider。记录两次失败和切换原因;
- 不得用本 skill 绕过任务或项目的路由授权。
- 不得无上限重试。
+ 先看实际外层退出码、`agent_status` 和 `final_answer`:结论、未完成事项、影响结果的问题以及文件路径。
+ 最终答复超过 12000 字符会标记截断,完整内容可从日志取得。runner 不提供中途注入指令、唤醒或自动完成通知;
+ 仍使用总控环境的托管句柄等待。
- 区分派发错误与测量数据:基础设施失败(起不来、超时、配置错)可按上一条重试;测量 provider/环境行为的派发,
- 一旦启动,失败必须计入原批次,禁止用重派结果替换或重试到成功,且必须固定并发度;本条优先于通用重试规则。
+ 汇总还包含:
- 修复性重试必须使用新的 task label,并同步用于 prompt、输出文件名和 Claude `--instance`,同时记录与原尝试的关联
- 标识;修复性重试不得并入原测量批次的通过率,如需重新测量,另建固定并发度、预定样本数的新批次。
+ - `runtime_exit_code` / `runner_exit_code` / `terminal`:进程与结构化终态。
+ - `session_id`:原生事件中的会话 ID(Codex thread_id / Claude session_id);缺失或冲突为 null。
+ 只有显式持久化的会话才可续接;ID 不证明默认一次性会话已保存。
+ - `validation_status`:`passed` 是机械检查通过;`needs_review` 提醒存在工具异常或可见性缺项;
+ `rejected` 是结构损坏、终态/最终答复缺失、进程失败或显式检查未满足。runtime 非零保留原码,否则机械拒收返回 1。
+ - `errors` / `anomalies` / `warnings`:最多每类 20 条、每条 2000 字符,附计数、截断和日志位置。
+ 普通工具失败列入 anomalies,成功 runtime 仍返回 0;并不自动判 Agent 或任务失败。
+ - `wall_clock_seconds`:runner 启动至调用结果收集器的实测秒数,含 setup/runtime/最终消息处理,
+ 不含收集器序列化、调用方预检和等待开销。`usage` 是单一终态的原始用量对象,不累计流式片段。
+ `runtime_metrics` 保留 Claude 报告的时长、费用和 modelUsage;缺失数据为 null/空对象,不估算。
+ 重复或缺失终态不提供可信用量;失败终态有真实用量时仍保留。完整原始统计也在日志中。
+ - `artifacts` / `canary_status`:只在调用方显式声明对应检查时有检查结果。
+ `result_status=not_assessed` 表示 runner 不替调用方判定任务正确性。
- 需要多轮延续时,第一次使用 `--persist`:
+ 传错参数、探索无匹配、权限错误等工具失败在 Agent 执行中常见。默认不要求逐事件裁决报告或固定 YAML。
+ 结合最终答复和任务目的判断结果是否可用;有未解决且影响结论的缺项时,核对相关日志/文件或要求补足。
+ 具体任务要求测试、独立来源或审核证据时,按这些要求核对;多个 Agent 一致或最终答复声称完成,不能替代所需证据。
+ 文件是否存在和内容是否符合任务也按交付需要核对,无需给所有任务设置统一 canary 或附加产物。
+ 最终答复中的工具调用语法且无记录的工具结果,只能提示可能的示例或未执行声明;runner 不据此断言伪造。
+ 按任务目的判断,要求实际执行的任务仍需核对执行结果。
+ `needs_review` 本身不要求用户追加授权、暂停 workflow 或重派;也不能只凭退出 0 推断业务正确。
- - Claude 后续使用返回的 session ID 配合 `--resume`;
- - Codex 后续使用 `--resume <id>` 或在明确需要时使用 `--resume-last`;
- - 一次性任务不得持久化 session。
+ 需要原始输出时加 `--detail`:恢复原始 stdout/stderr 行为,不自动汇总,也不执行可选 canary/产物收尾检查。
+ `--output-format text` 和 Claude `json` 仅用于此模式。它是输出选择,不额外要求调用方审计所有工具事件。
+ 子 Agent 的答复和 runner 的汇总都不构成用户授权。
- ## Controller Adjudication
+ ## 可选能力
- 子 Agent 输出只是输入证据。总控必须读取相关 artifact、review 关键代码或数据、交叉核对冲突,逐条处理可能
- 影响结论的工具失败,并自行采纳、部分采纳或驳回。不得因多个 Agent 表述一致或 final answer 没提失败就跳过证据检查。
+ 只有任务选择相应能力时才读取 [高级调用参考](references/advanced.md):
- 已派发任务只有取得进程终态并完成检查后,才填写完成报告的固定裁决块;预检失败可在确认子 Agent 未启动后
- 填写 `setup_status=fail` 的裁决块。在途时只作进度更新,记录托管句柄状态、
- 最近输出变化与尚未取得的退出码,不填写完成裁决块。值取自实际检查,不得凭印象;确实未检查的写 `unknown`,
- 不得把 `unknown` 当作通过:
+ - `sub-agent-preflight`:可选的提前 setup 检查及命令生成,默认自动 label,接受普通任务。
+ - `--canary`(preflight)或成对 runner canary 参数:验证指定文件读取,不证明整项任务正确。
+ - runner `--artifact`:显式检查本轮新建普通文件;通常直接用最终答复中的产物路径即可。
+ - `agent-sandbox --deny-list`:macOS/srt 的外层禁读边界,由调用方列出禁止路径和已知副本。
+ - `--full-access`:显式关闭内层沙箱及审批,本身没有任务级读取隔离。
- ```yaml
- setup_status: ok | fail | unknown # sub-agent-preflight 或手工预检的结果
- agent_status: completed | blocked | failed | not_started
- tool_evidence: yes | no | unknown # 至少一次可核对的工具执行;不代表全部必需取证已成功
- tool_trace: complete | partial | summary_only | missing | not_required | unknown # 可见轨迹范围
- required_evidence: complete | partial | missing | not_required | not_assessed # 任务必需证据经总控复核后的状态
- canary_status: match | mismatch | not_run | unknown
- result_status: accepted | partial | rejected | not_assessed # 总控对任务结论的裁定,独立于 agent_status
- warnings: [] # 已解释且不影响结论的诊断 / 工具失败逐条列出
- evidence_gaps: [] # 未解决的关键取证缺口;无则空列表
- retry_class: none | setup | provider | task | unknown
- ```
+ 默认工具权限与 provider 配置保持原样;工具权限不能扩张用户授权或任务 scope。
- `result_status=accepted` 只表示该子任务的证据与报告可采纳;code review 报告含 blocking finding 时,代码仍不得放行。
- `tool_trace=complete` 表示逐调用轨迹可核查,`partial` 表示有缺段,`summary_only` 表示只有 Claude 等汇总结果,
- `missing` 表示应有轨迹却没有;这组值不替代 `required_evidence` 的逐项复核。`partial` 或 `summary_only`
- 只有在全部必需证据经总控独立复核、且无其它硬性拒收条件时,才可支持 `result_status=accepted`。
- `agent_status` 记录进程 / 任务终态,`result_status` 记录报告可采纳性:进程退出 0、结构化终态成功但 canary 不匹配时,
- `agent_status=completed`、`result_status=rejected`,不能伪称进程失败。`agent_status=failed`、`canary_status=mismatch`
- 或 `setup_status=fail` 时,`result_status` 只能为 `rejected` 或 `not_assessed`;`agent_status=blocked` 或
- `not_started` 时不能为 `accepted`。任务要求工具调用而 `tool_evidence=no`,或任务有必需证据但
- `required_evidence` 不是 `complete` 时,受影响结论不能记为 `accepted`。验证类任务若 `canary_status`
- 不是 `match`,也不能记为 `accepted`。`tool_trace=summary_only`(Claude 默认 JSON)并不自动拒收;
- 须逐项独立复核必需证据并说明范围。`evidence_gaps` 非空时不能把受影响结论记为 `accepted`。
+ ## 失败、重试和会话
- `setup_status=fail` 时子 Agent 未启动:`agent_status` 必须写 `not_started`、`canary_status` 必须写 `not_run`、
- `result_status` 必须写 `not_assessed`、`retry_class` 写 `setup`。每次派发的裁决块后接人读叙述,逐个列出:
+ 启动前 setup 错误没有运行子 Agent:修正具体缺项后重新调用,不算 provider 重试或测量样本。
+ 已运行的实际失败先区分配置/环境故障、模型故障、任务问题;普通工具失败已经恢复且不影响结果时,无需重派。
+ 确需重派时最多一次有明确理由的同 provider 修复性重试,使用新的独立调用/日志并保留原尝试。
+ 再次失败后,遵守任务或项目的替补路由/授权;无额外限制时才可切换 provider。原因未知时先查清,不无限重试。
+ 测量任务一旦启动,失败计入原批次,不能用重试结果替换或重试到成功;固定并发度。
- - runtime、provider 和唯一 task label;
- - 子任务;
- - 退出状态的来源与数值;
- - stdout、stderr、last-message 或 artifact 路径;
- - 每条可观测的非豁免失败事件(Codex 优先用 `item.id`,否则用 JSONL 行号)、步骤、恢复证据及对结论的影响;
- Claude 汇总 JSON 无逐调用事件时明确说明;列出未解决的关键证据缺口;
- - 总控实际独立复核的关键文件、命令或数据范围,以及采纳、部分采纳或驳回的结论与理由;
- - retry、provider switch 和未解决风险。
+ 需要后续会话时首次使用 `--persist`,后续用返回的 session ID 配合 `--resume`(Codex 也有 `--resume-last`)。
+ 一次性任务无需持久化。外层禁读隔离不支持 resume 或中途追加输入。