#后台任务

开启 background: true（默认）后，长期 createLiteAgent() 会持有 session 范围的 后台工作。只需订阅一次即可观察普通用户轮次、child 事件和自主 completion 轮次；调用 close() 会取消仍在运行的工作并释放 session runner。

const agent = createLiteAgent({ model, workdir: process.cwd() });
const unsubscribe = agent.subscribe(({ sessionId, source, event }) => {
  render(sessionId, source, event);
});

await agent.send("派发代码审查");
await agent.send("它运行期间先回答另一个问题");

unsubscribe();
await agent.close();

#Bash 与 Agent 的生命周期不同

• bash 带 run_in_background: true 会启动 detached 进程，立即返回 bg_… id。用 BashOutput 读取增量输出，用 KillBackground 取消；它仍适用于 daemon。
• Agent 每次都会注册一个 detached 子代理组。其 run_in_background 输入只为 兼容解析，不能使组恢复为同步；background: false 则会让 Agent 派发明确失败。

一个 Agent group 只会在所有 child settle 后发出一次聚合的 background_completed 事件。随后所属 session 被唤醒，运行一次自主 completion；同一 session 的用户轮次和 completion 轮次串行执行。

query() 有意保持有限：关闭临时 agent 前，它会等待自己创建的 Agent groups 及其 自主 completion；不会等待不相关的 detached Bash daemon。若发起轮次返回后仍需交互， 请选择 createLiteAgent()。

#选项

backgroundLimits 字段：

#Completion 状态

在 background_completed 中查看 event.completion.status，它是权威结果。completed 表示全部 child 成功；partial 会同时保留成功输出和失败诊断；failed、cancelled 都不是成功。兼容字段 isError 由 status !== "completed" 派生。

for await (const event of query({ /* … */ })) {
  if (event.type === "background_completed") {
    console.log(event.completion.status, event.completion.content);
  }
}

#内置控制工具

两者仅在 background 开启时注册，也可用 allowedTools / disallowedTools 过滤。

#另请参阅

• 子代理——任务命名、组级送达与 pool 语义。
• Core 后台生命周期——状态和 XML 通知映射。
• 可观测性——消费 background_completed 事件。