# agent-squad 错误码映射

本轮不修改 Agent-Squad。当前 HTTP 层只有 `{"error":"<文本>"}`（`server.writeErr`），没有稳定码，也没有 trace。接入时把下表套进响应信封，正文理由仍放在 `reason`。

| 现状 | 规范码 | HTTP | 说明 |
|---|---|---|---|
| `role %s not found` | squad.role_not_found | 404 | `handleDeleteRole` 等 |
| `blueprint %s not found` | squad.blueprint_not_found | 404 | 蓝图删除 |
| Inspect / 黑板找不到运行 | squad.run_not_found | 404 | 磁盘为权威，重启后仍可能存在 |
| `goal.text is required` | squad.goal_required | 400 | 创建运行 |
| 运行处于 HITL 挂起（`RunStatus.IsHeld`） | squad.hitl_pending | 409 | 用 respond 续跑，不要并发再 Run |
| 计划确认 abort / 质检前的计划拒绝 | squad.plan_rejected | 422 | confirmation 挂起点拒绝 |
| 未知 backend，fail-closed | squad.unknown_backend | 400 | 禁止回落 stub |
| 步骤 `EvStepFailed` | squad.step_failed | 500 | 瞬时失败仍受步骤重试上限约束 |
| 质检失败且自动修复预算用尽 | squad.quality_failed | 422 | 可转 quality_review 人工放行 |
| `context cancelled` | squad.cancelled | 499 | 步骤保持 pending，可恢复 |
| 意图闸门守卫命中（`squadintent` 适配器，运行入口拒绝） | squad.intent_refused | 400 | 守卫"识别即拒绝"；按引导改写目标，不重试原文本 |
| JSON 解码失败 | sys.invalid_argument | 400 | 框架域，不单开小队码 |
| 未分类的 500 | sys.internal | 500 | 必须带 trace_id |

事件名（`step_failed`、`run_failed` 等）保持不变。事件文本里建议追加 `code` 字段，便于和日志系统的 `trace_id` 对齐。脱敏仍沿用现有 `Redact`，日志系统提供同形实现。

## 与执行错误的边界

步骤失败的根因优先用 agent 域码（例如 `agent.missing_deliverable`），小队只在编排层再包一层 `squad.step_failed`：

```text
squad.step_failed
  └─ agent.missing_deliverable
       └─ 原始执行错误
```

这样查 `squad.step_failed` 能看到编排后果，查 `agent.missing_deliverable` 能看到执行根因。