Background subagents

[dexhorthy]

HumanLayer Task

Why the change

Subagents can now run in the background while the launching agent keeps working, and the launcher is notified when each one finishes, the same way Claude Code's background agents behave, so hosts like HumanLayer can show and control them through one surface.

Special things to note

• The log format gains task_started / task_finished entries and an optional origin on user-message. Both are additive, and v1 logs still decode (there are tests for this). Exhaustive matches in fold-cli were updated for the new tags.
• interrupt() with no target now stops only foreground work; background tasks keep running and still notify. stop() and closing the session stop them. A stop the model makes with stop_agent sends no notification, but stopTask from the host does.
• The attached video shows the HumanLayer UI built on the matching Claude SDK feature (humanlayer/synclayer). Fold itself was checked with real Codex runs (codex/gpt-5.6-terra): two background agents, a wake per finish, then a clean exit; and list_agents → stop_agent → list_agents. Those runs caught two bugs (a list_agents schema OpenAI rejects, and an exit before the last notification) that are fixed here with regression tests.

Change outline

One background run, from launch to notification:

subagent { prompt, run_in_background: true }
  BackgroundTasks.launch
    write task_started
    fork child run into its own scope (from the session scope)
    return "Background agent started. agent_id: …"      # launcher's turn continues
  ... child works; task-progress deltas (last tool, counts)
  child run ends (completed | failed | stopped)
    write task_finished { status, summary, error, usage }
    release the child's scope, then queue the notification
      launcher busy → follow-up, delivered at its next natural completion
      root idle     → wake: new root run whose input is the notification
                      (same gate + running claim as send; queued notifications coalesce)

New durable rows and the user-message origin:

 LogEntry
+  task_started   { agentId, parentAgentId, toolCallId, taskType: 'subagent', agentType,
+                   description, prompt, isBackgrounded, runCount }
+  task_finished  { agentId, parentAgentId, toolCallId, status: completed|failed|stopped,
+                   summary, error, usage { turns, toolUses, totalTokens }, durationMs, lastToolName }
   user-message   { …,
+                   origin?: { _tag: 'task-notification', taskIds } }
 FoldEvent delta
+  task-progress  { lastToolName, counts }

Public surface:

 subagent tool params { description?, prompt, agent?, agent_id?, fork?, skill?,
+  run_in_background? }
+agentControlTools() → list_agents {}, stop_agent { agent_id }, send_message { agent_id, message }

 FoldSession
+  backgroundTasks: Effect<ReadonlyArray<BackgroundTask>>
+  backgroundTaskChanges: Stream<ReadonlyArray<BackgroundTask>>
+  stopTask(taskId): Effect<boolean, SubagentNotFoundError>
+  awaitBackgroundIdle: Effect<void>
~  interrupt(): foreground only; background tasks keep running

 foldcode
+  --background-timeout <seconds>   # --prompt waits for background agents (default 600)

BackgroundTask fields (taskId, toolCallId, parentAgentId, agentType, description, prompt, status, isBackgrounded, startedAt/endedAt/notifiedAt, usage, lastToolName, progressSummary, summary, error, runCount) map 1:1 onto HumanLayer's session_background_tasks table.

Where it lives:

packages/
├── fold-core/src/Subagents/
│   ├── BackgroundTasks.ts      # new: registry, run scopes, notification routing, wake
│   ├── AgentControlTools.ts    # new: list_agents / stop_agent / send_message
│   ├── SubagentEngine.ts       # dispatch/fork/resume in the background
│   └── SubagentTool.ts         # run_in_background param and receipt
├── fold-core/src/Api/OpenSession.ts       # session API, wake through the root gate
├── fold-core/src/EventLog/Schemas.ts      # new rows, user-message origin
├── fold-agent/src/Mode/{Mode,Rlm}.ts      # coding and RLM modes get the control tools
└── fold-cli/src/
    ├── Run.ts                  # --prompt settles background work before exit
    ├── Renderer.ts             # [background] / [notification] lines
    └── tui/                    # BG badge, "N RUN · M BG", x stops the selected agent, AGENTS row for wakes

Demo of the same feature in HumanLayer (Claude SDK side):

background-agents-demo.mp4

---