Harness spec 2.0.0: background work is a job — commands and subagents alike, seen and steered

One registry per process, every job owned by a session: bash's background commands (and a command
still running at its timeout, which now goes to the background instead of being killed) and
subagents started with task background: true. job_list, job_output, job_stop (the former
bash_list, bash_output, bash_kill) and the new job_send and report; a finished job wakes the owning
session in every front end with its marked note. The TUI counts jobs, lists them (/jobs), opens a
command's output, enters a subagent and messages it, moves a command to the background (ctrl+b)
and asks before quitting with jobs running. The link gains the jobs capability. Subagents get a
session row of their own, the spec's preamble and agent texts, and their errors reach the report.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

tests/subagent.test.ts

@@ -3,13 +3,39 @@ import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { join } from "node:path"
 import { createApp } from "../src/app.ts"
-import { Bus, type AskReply, type Event } from "../src/bus/index.ts"
+import { Bus, type Asker, type AskReply, type Event } from "../src/bus/index.ts"
 import { paths } from "../src/config/paths.ts"
 import { createView } from "../src/tui/state.ts"
+import { MARKS } from "../src/jobs/note.ts"
 import { delta, fakeProvider, toolCall, type Fake } from "./fake-provider.ts"
 
 let fake: Fake | undefined
-afterEach(() => fake?.stop())
+let other: Fake | undefined
+afterEach(() => (fake?.stop(), other?.stop(), (other = undefined)))
+
+/** Two scripted servers: the parent's model on `f`, the child's on `g` (task's `model: "g/m"`) —
+ *  a shared script would hand a reply to whichever engine asked first. */
+function pair(parent: Parameters<typeof fakeProvider>[0], child: Parameters<typeof fakeProvider>[0], o: { oneAtATime?: boolean; config?: string; asker?: Asker } = {}) {
+  fake = fakeProvider(parent)
+  other = fakeProvider(child)
+  mkdirSync(paths.config, { recursive: true })
+  writeFileSync(
+    join(paths.config, "connections.yaml"),
+    `connections:\n  f:\n    dialect: openai-chat\n    base_url: ${fake.url}\n    models: { m: {} }\n  g:\n    dialect: openai-chat\n    base_url: ${other.url}\n${o.oneAtATime ? "    one_model_at_a_time: true\n" : ""}    models: { m: {}, n: {} }\n`,
+    { mode: 0o600 },
+  )
+  writeFileSync(join(paths.config, "config.yaml"), `model: f/m\n${o.config ?? ""}`)
+  const cwd = mkdtempSync(join(tmpdir(), "ph-sub-"))
+  writeFileSync(join(cwd, "calc.py"), "def average(v):\n    return sum(v) / (len(v) - 1)\n")
+  const events: Event[] = []
+  const app = createApp({ cwd, mode: "edit", store: false, snapshots: false, asker: o.asker ?? { ask: async (): Promise<AskReply> => ({ kind: "once" }) } })
+  app.bus.on((e) => events.push(e))
+  return { app, events, cwd }
+}
+const settled = async (a: ReturnType<typeof createApp>, n: number) => {
+  const until = Date.now() + 8000
+  while (Date.now() < until && (fake!.requests.length < n || a.turns.current)) await Bun.sleep(20)
+}
 
 function app(script: Parameters<typeof fakeProvider>[0]) {
   fake = fakeProvider(script)
@@ -40,7 +66,14 @@ describe("subagents", () => {
     expect(child.messages[0].content).toContain('You are the "explore" subagent')
     expect(child.messages[0].content).not.toContain("Permission mode: plan")
     expect(child.messages.at(-1).content).toBe("Find why average is wrong in calc.py")
-    expect(names(child)).toEqual(["read", "glob", "grep", "list", "bash", "web_search", "web_fetch"])
+    // its own job tools for commands it starts, and report for a word to the main agent
+    expect(names(child)).toEqual(["read", "glob", "grep", "list", "bash", "job_output", "job_list", "job_stop", "web_search", "web_fetch", "report"])
+    // the preamble is the spec's text; a subagent is told nothing of plan_write or ask_user
+    expect(child.messages[0].content).toContain("Your final reply is your report to the main agent")
+    expect(child.messages[0].content).toContain("the report tool sends the main agent a message")
+    expect(child.messages[0].content).not.toContain("plan_write")
+    expect(child.messages[0].content).not.toContain("ask_user")
+    expect(child.messages[0].content).not.toContain("## Skills")
     // the parent gets the report, not the reading
     const result = fake!.requests[3].messages.at(-1).content as string
     expect(result).toStartWith("calc.py:2 divides by len(v) - 1")
@@ -60,7 +93,7 @@ describe("subagents", () => {
     ])
     await b.engine.prompt("review")
     const child = fake!.requests.find((r: any) => r.messages[0].content.includes('"reviewer" subagent'))
-    expect(names(child)).toEqual(["read", "grep"])
+    expect(names(child)).toEqual(["read", "grep", "report"])
     expect(child.messages[0].content).toContain("Review for bugs only.")
     expect(child.messages[0].content).toContain("you cannot change anything")
     const results = fake!.requests.at(-1).messages.filter((m: any) => m.role === "tool").map((m: any) => m.content as string)
@@ -152,3 +185,162 @@ test("a worktree subagent cannot touch the main checkout, even unrestricted", as
   expect(denied).toMatch(/outside the project|denied/)
   expect(git(root, ["branch", "--list", "lembas/*"]).out).toBe("")
 })
+
+describe("background subagents (spec 2.0.0)", () => {
+  test("task background: true returns at once; the report arrives as a marked note, a turn of its own", async () => {
+    const { app: a, events } = pair(
+      [
+        { chunks: [toolCall(0, "t1", "task", JSON.stringify({ description: "find the bug", prompt: "Find why average is wrong", model: "g/m", background: true }))] },
+        { chunks: [delta({ content: "Started it; carrying on." })] },
+        { chunks: [delta({ content: "Got the report." })] },
+      ],
+      [{ chunks: [toolCall(0, "r1", "read", '{"path":"calc.py"}')] }, { chunks: [delta({ content: "calc.py:2 divides by len(v) - 1." })] }],
+    )
+    await a.turns.prompt("look into it in the background")
+    const started = fake!.requests[1].messages.at(-1).content as string
+    expect(started).toStartWith("Started subagent explore as job1 (find the bug).")
+    await settled(a, 3)
+    const note = fake!.requests[2].messages.at(-1).content as string
+    expect(note).toStartWith(MARKS.subagent)
+    expect(note).toContain("job1 (explore: find the bug) finished after")
+    expect(note).toContain("calc.py:2 divides by len(v) - 1.")
+    expect(note).toContain("[explore subagent · 2 steps · 1 tool call]")
+    expect(events.find((e) => e.type === "sub_tool")).toMatchObject({ type: "sub_tool", callId: "t1", jobId: "job1", name: "read" })
+    expect(events.filter((e) => e.type === "job" && e.state !== "update").map((e) => e.type === "job" && `${e.job.kind} ${e.state}`)).toEqual(["subagent start", "subagent end"])
+    const job = a.jobs()[0]!
+    expect(job).toMatchObject({ id: "job1", kind: "subagent", state: "done", agent: "explore", model: "g/m", steps: 2, tools: 1 })
+    // Its transcript, for job_output and a panel: the tool line and what it wrote.
+    expect(job.output).toContain("[read]")
+    expect(job.output).toContain("calc.py:2 divides")
+    expect(job.subagent?.engine.messages.at(-1)).toMatchObject({ role: "assistant" })
+  })
+
+  test("job_send: to a running subagent at its next step under the to_subagent mark; to a finished one as a new prompt under the same id", async () => {
+    const { app: a, events } = pair(
+      [
+        // general, not explore: in plan mode `sleep` is refused at once, and the child would be at its next step before the message.
+        { chunks: [toolCall(0, "t1", "task", JSON.stringify({ description: "wait and look", prompt: "Wait, then look", model: "g/m", agent: "general", background: true }))] },
+        { chunks: [toolCall(0, "s1", "job_send", JSON.stringify({ id: "job1", text: "Also check X" }))] },
+        { chunks: [delta({ content: "Told it." })] },
+        { chunks: [toolCall(0, "s2", "job_send", JSON.stringify({ id: "job1", text: "And now Y" }))] },
+        { chunks: [delta({ content: "Asked for more." })] },
+        { chunks: [delta({ content: "All done." })] },
+      ],
+      [
+        { chunks: [toolCall(0, "b1", "bash", JSON.stringify({ command: "sleep 1", description: "wait" }))] },
+        { chunks: [delta({ content: "First report." })] },
+        { chunks: [delta({ content: "Second report." })] },
+      ],
+    )
+    await a.turns.prompt("go")
+    expect(fake!.requests[2].messages.at(-1).content).toContain("Sent to job1")
+    await settled(a, 6)
+    const child = other!.requests
+    const steered = child[1].messages.find((m: any) => m.role === "user" && String(m.content).startsWith(MARKS.to_subagent))
+    expect(steered?.content).toContain("Also check X")
+    expect(child[2].messages.at(-1).content).toBe("And now Y")
+    expect(fake!.requests[3].messages.at(-1).content).toContain("First report.")
+    expect(fake!.requests[4].messages.at(-1).content).toContain("is running again with your message")
+    expect(fake!.requests[5].messages.at(-1).content).toContain("Second report.")
+    expect(events.filter((e) => e.type === "job" && e.state !== "update").map((e) => e.type === "job" && e.state)).toEqual(["start", "end", "start", "end"])
+    expect(a.jobs()).toHaveLength(1)
+  })
+
+  test("report: a subagent's message reaches the main agent at its next step, marked; the final reply still comes", async () => {
+    const { app: a, events } = pair(
+      [{ chunks: [toolCall(0, "t1", "task", JSON.stringify({ description: "find loaders", prompt: "Find the loaders", model: "g/m" }))] }, { chunks: [delta({ content: "Thanks." })] }],
+      [{ chunks: [toolCall(0, "p1", "report", JSON.stringify({ text: "There are two loaders; which one?" }))] }, { chunks: [delta({ content: "Final: the YAML one." })] }],
+    )
+    await a.turns.prompt("go")
+    const msgs = fake!.requests[1].messages
+    const note = msgs.find((m: any) => m.role === "user" && String(m.content).startsWith(MARKS.message))
+    expect(note?.content).toContain("job1 (explore: find loaders):\nThere are two loaders; which one?")
+    // The note goes in after the step's tool results, as a steer does.
+    expect(msgs.at(-2)).toMatchObject({ role: "tool" })
+    expect(msgs.at(-2).content).toContain("Final: the YAML one.")
+    expect(other!.requests[1].messages.at(-1).content).toContain("Sent to the main agent")
+    expect(events.find((e) => e.type === "job_note")).toMatchObject({ type: "job_note", jobId: "job1" })
+    // The main agent itself has no report tool.
+    expect(names(fake!.requests[0])).not.toContain("report")
+  })
+
+  test("an approval from a subagent says which one asked (Asker source)", async () => {
+    const seen: unknown[] = []
+    const asker: Asker = {
+      ask: async (req) => {
+        seen.push(req.source)
+        return { kind: "once" }
+      },
+    }
+    const { app: a } = pair(
+      [{ chunks: [toolCall(0, "t1", "task", JSON.stringify({ description: "run it", prompt: "Run ls", model: "g/m", agent: "general" }))] }, { chunks: [delta({ content: "ok" })] }],
+      [{ chunks: [toolCall(0, "b1", "bash", JSON.stringify({ command: "true", description: "nothing" }))] }, { chunks: [delta({ content: "ran" })] }],
+      { asker },
+    )
+    await a.turns.prompt("go")
+    expect(seen).toEqual([{ jobId: "job1", agent: "general", description: "run it" }])
+  })
+
+  test("capacity: a second subagent is refused beside one already running on a one-model-at-a-time server", async () => {
+    const { app: a } = pair(
+      [
+        {
+          chunks: [
+            toolCall(0, "t1", "task", JSON.stringify({ description: "first", prompt: "wait", model: "g/m", background: true })),
+            toolCall(1, "t2", "task", JSON.stringify({ description: "second", prompt: "wait too", model: "g/n", background: true })),
+          ],
+        },
+        { chunks: [delta({ content: "ok" })] },
+        { chunks: [delta({ content: "done" })] },
+      ],
+      [{ chunks: [delta({ content: "slow" })], gapMs: 400 }],
+      { oneAtATime: true },
+    )
+    await a.turns.prompt("go")
+    const results = fake!.requests[1].messages.filter((m: any) => m.role === "tool").map((m: any) => m.content as string)
+    expect(results[0]).toStartWith("Started subagent explore as job1")
+    expect(results[1]).toContain("holds one model at a time, and a subagent is already running on g/m there")
+    expect(other!.requests.map((r: any) => r.model)).toEqual(["m"])
+    await settled(a, 3)
+  })
+
+  test("a broken agent file is said at start, and the agent is still offered with its body", () => {
+    mkdirSync(join(paths.config, "agents"), { recursive: true })
+    writeFileSync(join(paths.config, "agents", "broken.md"), "---\ndescription: [unclosed\nmode: plan\n---\nDo the thing.\n")
+    const { app: a } = pair([], [])
+    expect(a.loaded.warnings.some((w) => w.includes("broken.md") && w.includes("frontmatter not read"))).toBe(true)
+    const broken = a.agents.find((x) => x.name === "broken")!
+    expect(broken.instructions).toBe("Do the thing.")
+    expect(broken.mode).toBeUndefined()
+  })
+})
+
+test("a cancelled worktree subagent keeps its branch, and the result names it", async () => {
+  const { git } = await import("../src/git/run.ts")
+  const { app: a, events } = pair(
+    [{ chunks: [toolCall(0, "t1", "task", JSON.stringify({ description: "fix average", prompt: "Fix calc.py", agent: "general", worktree: true, model: "g/m" }))] }],
+    [
+      { chunks: [toolCall(0, "r1", "read", '{"path":"calc.py"}')] },
+      { chunks: [toolCall(0, "w1", "write", JSON.stringify({ path: "calc.py", content: "def average(v):\n    return sum(v) / len(v)\n" }))] },
+      { chunks: [delta({ content: "slow" })], gapMs: 3000 },
+    ],
+  )
+  const root = a.project.root
+  for (const args of [["init", "-q", "-b", "main"], ["config", "user.email", "t@e"], ["config", "user.name", "T"], ["config", "commit.gpgsign", "false"], ["add", "calc.py"], ["commit", "-q", "-m", "init"]]) git(root, args)
+  ;(a.project as any).gitRoot = root
+  const turn = a.turns.prompt("fix it in a worktree")
+  const until = Date.now() + 8000
+  while (Date.now() < until && !events.some((e) => e.type === "sub_tool" && e.name === "write")) await Bun.sleep(20)
+  const write = events.find((e) => e.type === "sub_tool" && e.name === "write")
+  expect(write && write.type === "sub_tool" ? write.title : "").not.toMatch(/denied|refused|outside|not read/i)
+  await Bun.sleep(100)
+  a.cancel()
+  expect(await turn).toBe("cancelled")
+  const result = a.engine.messages.find((m) => m.role === "tool")!
+  expect(result.role === "tool" && result.content).toContain("ended: cancelled")
+  const branch = /branch (lembas\/general-fix-average-[a-z0-9]+)/.exec(result.role === "tool" ? result.content : "")?.[1]
+  expect(branch).toBeTruthy()
+  expect(git(root, ["log", "-1", "--format=%s", branch!]).out).toBe("general: fix average (stopped)")
+  expect(git(root, ["show", `${branch}:calc.py`]).out).toContain("sum(v) / len(v)")
+  expect(a.jobs()[0]).toMatchObject({ kind: "subagent", state: "stopped" })
+})