#Background tasks

With background: true (the default), a long-lived createLiteAgent() owns session-scoped background work. Subscribe once to observe ordinary user turns, child events, and autonomous completion turns; call close() to cancel live work and release the session runner.

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

await agent.send("Delegate the review");
await agent.send("Answer another question while it runs");

unsubscribe();
await agent.close();

#Bash and Agent have different lifecycles

• bash with run_in_background: true starts a detached process and returns a bg_… id immediately. Use BashOutput to read incremental output and KillBackground to cancel it. This remains suitable for daemons.
• Agent always registers one detached subagent group. Its run_in_background input is accepted only as a compatibility adapter and cannot make the group synchronous. background: false instead rejects Agent dispatch explicitly.

An Agent group emits one aggregate background_completed event only after all children settle. The owning session is then woken for one autonomous completion turn; user turns and completion turns are serialized per session.

query() is deliberately finite: it waits for Agent groups it created and their autonomous completion turns before closing its temporary agent. It does not wait for unrelated detached Bash daemons. Choose createLiteAgent() for work that must remain interactive after the initiating turn returns.

#Options

backgroundLimits fields:

#Completion status

Inspect event.completion.status in background_completed; it is the authoritative result. completed means every child succeeded. partial keeps both successful output and unsuccessful diagnostics; failed and cancelled are not successes. The compatibility isError field is derived as status !== "completed".

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

#Built-in controls

Both are registered only when background is enabled and can be filtered with allowedTools / disallowedTools.

#See also

• Subagents — task naming, group delivery, and pool semantics.
• Core background lifecycle — statuses and XML notification mapping.
• Observability — consuming background_completed events.