Native background subagent launch failures are not surfaced to the parent task
- Dominant language
- TypeScript
- Stars
- 2.7k
- Forks
- 395
- Avg merge
- 21h 48m
- Merged PRs (30d)
- 776
Description
**客户端版本**: 0.1.55
**反馈类型**: bug
---
## 现象
原生后台 subagent 在进入 Claude Agent SDK 的 task 生命周期之前失败时(例如显式指定的模型对当前账号不可用),失败会写入 sidechain transcript,但不会作为可查询的失败任务或终态通知回传给父会话。
## 复现步骤
1. 启动一个原生后台 subagent,并显式选择当前账号无权访问的模型。
2. subagent 启动阶段收到 403 鉴权/授权失败。
3. 通过父会话的任务接口(`TaskOutput` / task list)查询该 subagent。
4. 检查该 agent 对应的 sidechain transcript。
## 期望行为
- 父会话收到明确的终态失败通知。
- 任务保留为可查询的 `failed` 状态,而不是消失。
- 失败信息能够说明发生在 launch 阶段,并提供安全、结构化的错误摘要。
- 理想情况下,对当前账号不可用的显式模型应在创建 sidechain/worktree 前被拒绝。
## 实际行为
- 父任务查询返回 `No task found`,任务列表为空。
- 父 agent 没有收到终态失败通知。
- sidechain transcript 中存在 synthetic terminal error,说明失败已被记录,但没有桥接到父会话可见的任务生命周期。
## 复现频率
每次显式指定当前账号无权访问的模型启动原生后台 subagent 时均可复现。
## 已尝试
- 查询任务列表和任务输出:该 agent ID 已不可发现,返回 `No task found`。
- 随后检查 sidechain transcript。
## 已脱敏诊断摘要
sidechain 终态记录是 synthetic assistant message,并包含:
- `error: authentication_failed`
- HTTP 状态 `403`
- `isSidechain: true`
- 请求的 Claude 模型不允许当前账号访问
这表明失败发生在正常 SDK `task_started` / `task_updated` / `task_notification` 序列产生之前。现有 subagent observation 能处理启动后的 task 事件,但 launch/pre-task failure 没有被规范化到同一套父会话可见的失败任务协议。
## 建议方向
从 subagent 创建开始维护宿主拥有的 launch record。若发生启动、进程、路由或鉴权失败,将其规范化为结构化 `failed` 终态,持久化、可查询,并通知父会话。若启动前能获得模型访问能力信息,则应预先校验显式选择的模型,避免创建一个会立即失败的 sidechain。
---
**版本区域**: CN
**OS**: darwin arm64 (25.6.0)
**界面语言**: zh-CN
Contributor guide
Research direction
Start by tracing native background subagent creation and the parent TaskOutput/task-list handling, then compare launch failures with the task_started, task_updated, and task_notification sequence. Check how the sidechain transcript records the synthetic terminal error. Done means a pre-task failure remains queryable as a structured failed task and produces a terminal notification to the parent session.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- ai, backend-api-design
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100