diff --git a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionEngine.swift b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionEngine.swift
index 4a20cbc4d..e1fe9699a 100644
--- a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionEngine.swift
+++ b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionEngine.swift
@@ -36,7 +36,8 @@ final class ClaudeSessionEngine {
/// Subagents reported done before anything else was known of them;
/// the end applies once they are.
var endedAgents: [String: Date] = [:]
- /// Commands left running in the background, by the call that started them.
+ /// Commands and subagents left running in the background, by the call
+ /// that started them.
var background: [String: Background] = [:]
var tasks: ClaudeTaskProgress?
var usage: [String: (tokens: AgentTokens, cost: Double)] = [:]
@@ -242,11 +243,12 @@ final class ClaudeSessionEngine {
// Claude Code says "shell" for a session at rest with a command of its
// own still running in the background. The work is not done while one
// it waits for runs; a dev server or an emulator left running is not
- // work, and when nothing was seen start, it counts as work.
- if record.status == .shell {
- let running = entry.runningBackground
- if running.isEmpty || running.contains(where: { !$0.service }) { return .background }
- }
+ // work, and when nothing was seen start, it counts as work. While a
+ // subagent it sent to the background works, it says "busy" though
+ // the turn ended.
+ let running = entry.runningBackground
+ if record.status == .shell, running.isEmpty || running.contains(where: { !$0.service }) { return .background }
+ if record.status == .busy, running.contains(where: { !$0.service && $0.task != nil }) { return .background }
if let ended = entry.turnEnded, entry.completed, now.timeIntervalSince(ended) < finishedFor,
(entry.acknowledged ?? .distantPast) < ended {
return .finished
@@ -288,7 +290,7 @@ final class ClaudeSessionEngine {
title: previews ? entry.title : nil, lastText: previews ? entry.lastText : nil,
hooked: entry.hooked, chat: previews ? entry.chat : [],
backgroundLabel: previews ? entry.runningBackground.last { !$0.service }?.label : nil,
- services: record.status == .shell ? entry.runningBackground.filter(\.service).count : 0)
+ services: record.status == .shell || phase == .background ? entry.runningBackground.filter(\.service).count : 0)
}
// MARK: Rules
@@ -359,7 +361,7 @@ final class ClaudeSessionEngine {
/// The notice and the registry's change are written apart.
static let askedSlack: TimeInterval = 5
- /// Background commands kept per session, the ended ones going first.
+ /// Background commands and subagents kept per session, the ended ones going first.
static let backgroundKept = 40
/// The conversation keeps its latest messages.
@@ -504,6 +506,8 @@ final class ClaudeSessionEngine {
}
// The tool that asked ran or was refused, here or in the terminal.
entry.permissions.removeAll { $0.toolID == id }
+ // A background command refused before it ran got no id and never ends.
+ if failed, let job = entry.background[id], job.task == nil, job.ended == nil { entry.background[id]?.ended = date }
touch(date, in: &entry)
}
diff --git a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionModels.swift b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionModels.swift
index 61260377b..969fa88e8 100644
--- a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionModels.swift
+++ b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionModels.swift
@@ -14,8 +14,8 @@ enum ClaudeSessionPhase: String, Equatable {
case waitingPermission
/// A question, dialog or other prompt waits for the person.
case waitingInput
- /// The turn ended but a command it started, like a render, still runs
- /// in the background; Claude Code hears when it ends.
+ /// The turn ended but a command it started, like a render, or a subagent
+ /// it sent off still runs in the background; Claude Code hears when it ends.
case background
/// The turn ended and the person has not looked at it yet.
case finished
@@ -322,10 +322,11 @@ enum ClaudeTranscriptFact: Equatable {
case usage(key: String, tokens: AgentTokens, cost: Double)
case subagentActivity(id: String, at: Date)
case subagentEnded(id: String, at: Date)
- /// A command the model left running in the background; a service, like
- /// a dev server or an emulator, is meant to keep running.
+ /// A command the model left running in the background, or a subagent it
+ /// sent there; a service, like a dev server or an emulator, is meant to
+ /// keep running.
case backgroundStarted(toolID: String, service: Bool, label: String?, at: Date)
- /// The id Claude Code gave that command, which its end notice names.
+ /// The id Claude Code gave that command or subagent, which its end notice names.
case backgroundTask(toolID: String, task: String)
case subagentInfo(id: String, type: String, description: String?)
case tasks(ClaudeTaskProgress)
diff --git a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionService.swift b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionService.swift
index 446148780..9d5e5751b 100644
--- a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionService.swift
+++ b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeSessionService.swift
@@ -322,6 +322,12 @@ final class ClaudeSessionService: ObservableObject {
} else {
connection.finish()
}
+ // A turn's lines are written before its Stop hook runs; reading them
+ // first tells whether it left work in the background, before a notice
+ // calls it done.
+ if case .stopped = message.fact.event, let path = transcripts[message.fact.sessionID] {
+ read(path, session: message.fact.sessionID, now: now)
+ }
engine.ingest(hook: message.fact, now: now)
publish(now: now)
}
diff --git a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeTranscriptReader.swift b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeTranscriptReader.swift
index 8ad6e2de0..d767e34b2 100644
--- a/Sources/Vorssaint/Services/ClaudeSessions/ClaudeTranscriptReader.swift
+++ b/Sources/Vorssaint/Services/ClaudeSessions/ClaudeTranscriptReader.swift
@@ -107,9 +107,18 @@ struct ClaudeTranscriptReader {
for result in results {
guard let id = result["tool_use_id"] as? String else { continue }
facts.append(.toolFinished(id: id, at: date, failed: result["is_error"] as? Bool == true))
- if let task = (json["toolUseResult"] as? [String: Any])?["backgroundTaskId"] as? String, !task.isEmpty {
+ let outcome = json["toolUseResult"] as? [String: Any]
+ if let task = outcome?["backgroundTaskId"] as? String, !task.isEmpty {
facts.append(.backgroundTask(toolID: id, task: task))
}
+ // A subagent sent to the background answers at once with
+ // its id; Claude waits for it as for a render.
+ if outcome?["isAsync"] as? Bool == true || outcome?["status"] as? String == "async_launched",
+ let agent = outcome?["agentId"] as? String, !agent.isEmpty {
+ let label = policy.previews ? preview(outcome?["description"] as? String) : nil
+ facts.append(.backgroundStarted(toolID: id, service: false, label: label, at: date))
+ facts.append(.backgroundTask(toolID: id, task: agent))
+ }
}
if json["toolEndsTurn"] as? Bool == true { facts.append(.turnEnded(date, completed: true)) }
break
diff --git a/Tests/ClaudeSessionEngineTests.swift b/Tests/ClaudeSessionEngineTests.swift
index 1864b6a7f..c0f58679c 100644
--- a/Tests/ClaudeSessionEngineTests.swift
+++ b/Tests/ClaudeSessionEngineTests.swift
@@ -159,6 +159,73 @@ enum ClaudeSessionEngineTests {
"work it waits for keeps it in the background, saying what")
services.ingest(sessionID: "s1", facts: [.subagentEnded(id: "b3", at: at(9))], now: at(9))
suite.expect(only(services, 10)?.phase != .background, "once that work ends, the services alone do not hold it there")
+ // Claude Code stays "busy" while subagents it sent to the background
+ // work, and the turn that sent them still ends with its Stop hook.
+ let explore = ClaudeSessionEngine(policy: ClaudeContentPolicy(previews: true))
+ explore.ingest(records: [record(status: .busy, changed: 0)], now: at(0))
+ explore.ingest(sessionID: "s1", facts: [
+ .turnBegan(at(1)),
+ .backgroundStarted(toolID: "t1", service: false, label: "Map friends tab", at: at(2)), .backgroundTask(toolID: "t1", task: "a1"),
+ .backgroundStarted(toolID: "t2", service: false, label: "Map poll design", at: at(3)), .backgroundTask(toolID: "t2", task: "a2"),
+ ], now: at(2))
+ _ = explore.snapshot(now: at(3))
+ explore.ingest(sessionID: "s1", facts: [.turnEnded(at(10), completed: true)], now: at(10))
+ explore.ingest(hook: hook(.stopped(lastText: "Waiting for both agents"), 10), now: at(10))
+ let sentOffSnapshot = explore.snapshot(now: at(11))
+ let sentOff: ClaudeSession? = sentOffSnapshot.sessions.first
+ suite.expect(sentOff?.phase == .background, "a turn that left subagents working in the background is not done")
+ suite.expect(sentOff?.backgroundLabel == "Map poll design", "and says what it waits for")
+ suite.expect(sentOffSnapshot.events.isEmpty, "so no notice says it finished")
+ explore.ingest(sessionID: "s1", facts: [.subagentEnded(id: "a1", at: at(100)), .turnBegan(at(100))], now: at(100))
+ suite.expect(only(explore, 101)?.phase == .generating, "the first one's end takes the turn up again")
+ explore.ingest(sessionID: "s1", facts: [.turnEnded(at(105), completed: true)], now: at(105))
+ let second = explore.snapshot(now: at(106))
+ let left2: ClaudeSession? = second.sessions.first
+ suite.expect(left2?.phase == .background && second.events.isEmpty, "while the other still works it stays in the background")
+ explore.ingest(sessionID: "s1", facts: [.subagentEnded(id: "a2", at: at(200)), .turnBegan(at(200))], now: at(200))
+ _ = explore.snapshot(now: at(201))
+ explore.ingest(sessionID: "s1", facts: [.turnEnded(at(230), completed: true)], now: at(230))
+ explore.ingest(records: [record(status: .idle, changed: 230)], now: at(230))
+ let done = explore.snapshot(now: at(231))
+ let noticed = done.events.contains { if case .finished = $0 { return true }; return false }
+ suite.expect(done.sessions.first?.phase == .finished && noticed, "once both are done and the turn ends, it finished, with a notice")
+ let served = ClaudeSessionEngine()
+ served.ingest(records: [record(status: .busy, changed: 0)], now: at(0))
+ served.ingest(sessionID: "s1", facts: [
+ .turnBegan(at(1)),
+ .backgroundStarted(toolID: "t1", service: true, label: "Run own Metro", at: at(2)), .backgroundTask(toolID: "t1", task: "b1"),
+ .turnEnded(at(10), completed: true),
+ ], now: at(10))
+ suite.expect(only(served, 11)?.phase == .finished, "while the registry trails the end, a service alone does not hold it")
+ served.ingest(sessionID: "s1", facts: [
+ .backgroundStarted(toolID: "t2", service: false, label: "Map the app", at: at(12)), .backgroundTask(toolID: "t2", task: "a1"),
+ ], now: at(12))
+ suite.expect(only(served, 13)?.services == 1, "beside a subagent in the background it says what else runs")
+ // A background command refused before it ran gets no id and never ends.
+ let refused = ClaudeSessionEngine()
+ refused.ingest(records: [record(status: .busy, changed: 0)], now: at(0))
+ refused.ingest(sessionID: "s1", facts: [
+ .turnBegan(at(1)), .toolStarted(tool("b1", 2)),
+ .backgroundStarted(toolID: "b1", service: false, label: "Submit the build", at: at(2)),
+ .toolFinished(id: "b1", at: at(3), failed: true),
+ ], now: at(3))
+ _ = refused.snapshot(now: at(5))
+ refused.ingest(sessionID: "s1", facts: [.turnEnded(at(10), completed: true)], now: at(10))
+ let trailing = refused.snapshot(now: at(10.5))
+ refused.ingest(records: [record(status: .idle, changed: 11)], now: at(11))
+ let refusedNoticed = (trailing.events + refused.snapshot(now: at(11.5)).events).contains { if case .finished = $0 { return true }; return false }
+ suite.expect(trailing.sessions.first?.phase != .background && refusedNoticed,
+ "a background command refused before it ran holds nothing, and the turn's end is still told")
+ let lostEnd = ClaudeSessionEngine()
+ lostEnd.ingest(records: [record(status: .busy, changed: 0)], now: at(0))
+ lostEnd.ingest(sessionID: "s1", facts: [
+ .turnBegan(at(1)),
+ .backgroundStarted(toolID: "t1", service: false, label: nil, at: at(2)), .backgroundTask(toolID: "t1", task: "a1"),
+ .turnEnded(at(10), completed: true),
+ ], now: at(10))
+ lostEnd.ingest(records: [record(status: .idle, changed: 20)], now: at(20))
+ suite.expect(only(lostEnd, 21)?.phase == .finished, "an end not read does not hold it once the registry goes idle")
+
let unseen = ClaudeSessionEngine()
unseen.ingest(records: [record(status: .shell, changed: 0)], now: at(0))
suite.expect(only(unseen, 1)?.phase == .background, "a command running that was never seen start counts as work")
diff --git a/Tests/ClaudeSessionReaderTests.swift b/Tests/ClaudeSessionReaderTests.swift
index 6b90d3a23..2a4e2e933 100644
--- a/Tests/ClaudeSessionReaderTests.swift
+++ b/Tests/ClaudeSessionReaderTests.swift
@@ -163,6 +163,18 @@ enum ClaudeSessionReaderTests {
suite.expect(parse([started], previews: false).contains(.backgroundStarted(toolID: "tb1", service: true, label: nil,
at: date("2026-10-22T10:00:00.000Z"))),
"with previews off it is still told apart, without its words")
+ let sent = #"{"type":"user","timestamp":"2026-10-22T13:14:15.571Z","toolUseResult":{"isAsync":true,"status":"async_launched","agentId":"a758ef93113160fa0","description":"Map friends tab and add flow"},"message":{"role":"user","content":[{"tool_use_id":"ta1","type":"tool_result","content":[{"type":"text","text":"Async agent launched successfully."}]}]}}"#
+ let waited = #"{"type":"user","timestamp":"2026-10-22T13:14:20.000Z","toolUseResult":{"status":"completed","agentId":"a1","description":"Look around"},"message":{"role":"user","content":[{"tool_use_id":"ta2","type":"tool_result","content":"Done."}]}}"#
+ let agents = parse([sent, waited], previews: true)
+ suite.expect(agents.contains(.backgroundStarted(toolID: "ta1", service: false, label: "Map friends tab and add flow",
+ at: date("2026-10-22T13:14:15.571Z")))
+ && agents.contains(.backgroundTask(toolID: "ta1", task: "a758ef93113160fa0")),
+ "a subagent sent to the background is work Claude waits for, under its own id")
+ suite.expect(!agents.contains { if case .backgroundStarted(let id, _, _, _) = $0 { return id == "ta2" }; return false },
+ "a subagent that answered before the turn went on is not")
+ suite.expect(parse([sent], previews: false).contains(.backgroundStarted(toolID: "ta1", service: false, label: nil,
+ at: date("2026-10-22T13:14:15.571Z"))),
+ "with previews off without what it does")
let notice = #"{"type":"user","origin":{"kind":"task-notification"},"timestamp":"2026-10-21T19:06:34.760Z","message":{"role":"user","content":"\na05df\ncompleted\n"},"sessionId":"s1"}"#
let queued = #"{"type":"queue-operation","operation":"enqueue","timestamp":"2026-10-21T19:06:30.000Z","content":"b77failed"}"#
diff --git a/docs/claude-sessions-spike.md b/docs/claude-sessions-spike.md
index 17eafa30b..e85bb43c0 100644
--- a/docs/claude-sessions-spike.md
+++ b/docs/claude-sessions-spike.md
@@ -49,6 +49,7 @@ Not run end to end: the Always answer, which hands back `permission_suggestions`
## Later findings (2.1.307)
- The registry says `"shell"` for a session at rest while a command it started in the background still runs (`status === "idle" && ? "shell"`). The island shows it as working in the background, not done.
+- While a subagent sent to the background works, the registry stays `"busy"` (`isLoading || delegatedActive`) though the turn that sent it ended with `end_turn` and the Stop hook (2.1.308). Its `Agent` result carries `toolUseResult` `isAsync: true`, `status: "async_launched"`, `agentId` and `description`, and its end comes as a `` naming that `agentId`. The island shows the session in the background until then; the registry going idle releases it if the end was missed.
- `"dialog open"` covers every dialog in the terminal, including ones the person opens, like `/usage`. Only dialogs Claude Code raises itself send a Notification hook.
- Claude Code attaches an image when a paste is nothing but the path of a PNG, JPEG, GIF or WebP file, and reads the file a moment later. A return sent at once goes out without it. Terminal adds a return after every `do script`, so the image paths go first with a paste left open, which that return joins as a line break; after a pause the text closes the paste and its return sends the reply. Confirmed in a throwaway session: the transcript held the image block and the model described the picture.