Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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)] = [:]
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
67 changes: 67 additions & 0 deletions Tests/ClaudeSessionEngineTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
12 changes: 12 additions & 0 deletions Tests/ClaudeSessionReaderTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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":"<task-notification>\n<task-id>a05df</task-id>\n<status>completed</status>\n</task-notification>"},"sessionId":"s1"}"#
let queued = #"{"type":"queue-operation","operation":"enqueue","timestamp":"2026-10-21T19:06:30.000Z","content":"<task-notification><task-id>b77</task-id><status>failed</status></task-notification>"}"#
Expand Down
1 change: 1 addition & 0 deletions docs/claude-sessions-spike.md
Original file line number Diff line number Diff line change
Expand Up @@ -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" && <background shell> ? "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 `<task-notification>` 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.

Expand Down
Loading