A distinct state for "at prompt, background work pending" (and a state API from agent CLIs)

[tjs0]

I run Claude Code, Codex and Antigravity side by side in Herdr and use the sidebar's state ball as my attention queue. The ball often says a pane needs me when the agent is actually waiting on its own background work: subagents (#5004, #2354) and background shells. The agent resumes the turn by itself when that work reports back, so nothing is needed from me.

From #5004 and #4735 I understand why Herdr reads those panes as idle: the agent is at its prompt and takes input, and automation that waits for idle depends on that. Both readings are right for different consumers. "Can I send a prompt?" and "Does this agent need my attention?" are different questions, and one state answers only one of them.

Idea: a separate signal for "at prompt, background work pending". It could be a state or a flag next to idle. Automation can keep treating it as idle, and the sidebar can show it as busy instead of done. It would also let the sidebar handle the dev-server case from #4735 differently from a subagent the turn is waiting on, if the screen can tell them apart.

A longer-term note: all of this is inferred from the screen, and it breaks each time an agent CLI changes its footer (2.1.28x showed ↓ to manage, 2.1.299 doesn't). A real fix would be for the agent CLIs to expose their state through an API: working, waiting on background work, waiting for permission or an answer, done. Herdr could then read state instead of scraping it. There's already a start: #5004 notes that claude agents --json reports the session as busy while the screen reads idle. If Herdr asked the CLI vendors for one shared signal, the request would carry more weight coming from Herdr than from individual users. Is there interest in that direction?

[rcollette]

+1, and the same applies to GitHub Copilot CLI. When Copilot starts background task subagents and returns to its prompt, the pane and its workspace show idle/done (green) even though the subagents are still working and the turn will resume when they report back. I'd like both the agent row and the workspace indicator to show busy (yellow) while any subagent is running, even if automation keeps treating the pane as idle. Related Copilot bug: #4329.

[spawnia]

+1, with an automation use case for the flag.

We run a router that starts Claude Code sessions in Herdr and caps how many may wait on the user at once.
A session whose turn ended with a run_in_background shell still running reads idle or done, so it takes a slot it does not need.

For now we read status: "shell" from ~/.claude/sessions/<pid>.json, as suggested in #3414.
A flag next to idle in herdr agent list would let us drop that workaround.

[zztalker]

+1. I hit this every day with Claude Code, in both the Herdr desktop app (herdr-core) and Herdr 0.9.5. When a turn ends while its own run_in_background shells or a Monitor are still running, the pane shows done and the "finished" notification fires. A minute later the agent wakes up by itself. With a few agents doing that, done stops meaning done. (#1217, #3525, #5004)

I wanted to know whether a separate state holds up in practice, so I tried it in my forks. This is a prototype for discussion, not a PR.

Where the signal is

• Desktop app / herdr-core: Claude Code reports state=done over OSC 7501 as soon as the turn ends. It sends no records, even with three shells still running (seen with hc events). So core has nothing to go on. Claude does record it in ~/.claude/sessions/<pid>.json: status goes busy → shell → busy, and shell lasts exactly as long as the background shell runs (sampled every 2 s, 2.1.316). This is the same field Claude Code pane reports working while idle at the prompt with a background shell running #3414 and the router comment above use.
• Herdr 0.9.5 / screen: two places on screen are stable. The turn summary: ✻ Worked for 1m 26s · done 1:30 PM · 3 shells still running. And the footer: ⏵⏵ auto mode on · 3 shells · ↓ to manage (2.1.316), or · 3 shells, 1 monitor · (2.1.258, background_shell_working misses "N shells, N monitor" and monitor-only footers (follow-up to #2241) #3525).

What I tried

1. herdr-core: hc report <7501 body>. A hook has no tty, so it can't write 7501 itself (herdr-core#42). The body goes through the same Ghostty parser and lands in the same records as screen output. No screen reading and no vendor logic in core.
2. A Claude Code Stop hook: while the session file says shell, it reports a child record state=working:id=bg. It clears the record when the shells end or a new turn starts. Claude's own root state is untouched.
3. herdr-app: when an agent's root state is idle/done and a record is still working, it shows waiting: a slow, faded spinner and a "Waiting" group. Entering waiting doesn't notify. Leaving it does, which is the notification I actually want.
4. Herdr 0.9.5: a Waiting agent state, ranked below working and above idle. Plus a Claude rule built from the screens above; it needs engine 4, and the published manifest is staged.

Open questions (your call)

• Dev servers (Claude Code pane reports working while idle at the prompt with a background shell running #3414, agy: background_tasks_working keeps an idle pane working while a server started in an earlier turn is still running #4735): a server left running from an earlier turn also reads as waiting. I think that's accurate: the agent does own running work, and unlike done it doesn't notify anyone. But it's the case that led to "count as idle".
• agent wait default: my prototype leaves waiting out of the default set, so you ask for it with --until waiting. agy: background_tasks_working keeps an idle pane working while a server started in an earlier turn is still running #4735 and the automation above want it to behave like idle. A flag next to idle, as this thread proposes, sidesteps that; a separate state forces a choice.
• hc report: it widens core's "status comes only from 7501" rule to "7501 reports from the program or its hook". Is that acceptable, or would you solve herdr-core#42 another way?

I know unsolicited PRs are closed, so I'm not opening any. If any part is wanted, the branches are based on today's master and tested: herdr has 4,132 tests passing with fmt and clippy clean; herdr-core's full suite and clippy pass; herdr-app has 244 tests passing.

• herdr: feat/waiting-state. Commit 1e37217, compare
• herdr-core: feat/waiting-sub-status. Commit 3a007ba, compare
• herdr-app: feat/waiting-sub-status. Commits ea588ca (waiting in the app) and 2363961 (Claude hook), compare

Related: #1217, #3525, #5004, #5007, #3414, #4735, #4329, #4511, #2354, herdr-core#42.

[zztalker]

Update on the prototype: for the desktop app, only the herdr-core change is needed. herdr-app needs no change; a mod or a layout does the rest.

• herdr-core: herdr-core#81 adds hc report, so a hook with no terminal can apply a 7501 report. The Claude Code Stop hook uses it to set a child record bg to working while background shells run, and clears it when they end. Claude's own state is untouched.
• herdr-app: mods already get every terminal's records from terminals(). A mod treats an agent whose own status is idle and whose bg record is working as waiting. agents(), idle and the defaults stay as they are for automation. A done agent stays Done until it has been seen.

So the herdr-app branch from my first comment isn't needed. Examples:

• herdr-agent-waiting-mod: the shipped agents mod with a Waiting section, and the Claude Code hook with an installer. Its dev-server example is a recorded run: an agent starts two background monitors and is opened after each finish, so it goes Working → Done → Waiting → Working → Done → Waiting → Working → Done.
• herdr-agent-deck: a layout with the same rule in its own Agents panel, and waiting agents in the Overview's Working lane.

Until #81 is merged, they need a herdr-core build of that branch: 0.1.18-report.1 (Linux x86_64, macOS arm64, unofficial).

What a mod still can't do is hold back the done sound and toast while background work runs. That would need herdr-app itself.

[zztalker]

Update on the Herdr 0.9.5 (TUI) prototype from my first comment: I reworked it from a new waiting state into a flag next to the state. Waiting is now information beside the agent's state, not a replacement for it, which matches my answer on readiness and what the desktop app does with core's bg record.

• State unchanged: an agent at its prompt with background work running stays idle, or done until it's viewed. agent wait, agent prompt --wait and notifications behave exactly as on master, which covers the automation cases in agy: background_tasks_working keeps an idle pane working while a server started in an earlier turn is still running #4735 and the router comment.
• The flag: agent, pane, tab and workspace records and pane.agent_status_changed gain background_work: true while that work runs. This is the "flag next to idle" this thread proposed.
• Detection: a manifest rule can set background_work = true without a state, and it only counts while the state is idle. Claude's manifest uses it for the N shells still running turn summary and the · N shells · footer (engine 4; released clients keep the current published manifest).
• Sidebar: a finish you haven't viewed still shows as done. Once viewed, the agent shows as waiting (◌ / ◔), ranked between working and idle, and the navigator's working filter includes it.

The branch is the same, feat/waiting-state, now at commit 4304fb1 (compare). It replaces 1e37217 from my first comment.

[AndreVianna]

Separating those states makes sense, but I wonder whether readiness should be informational rather than a delivery guarantee. Background work could resume between checking the state and sending a message. I’d lean toward having the delivery operation accept, queue or reject the message based on the state at that moment. Is there a reason the router should make that decision instead?

[zztalker]

Agreed. Waiting should be information, not a promise that a message is safe to send, and that's how I built the prototype.

In herdr-core, waiting is not a new state for the agent. The agent's own state stays done/idle and its turn doesn't change. The background work shows up next to it as a child record (id=bg, working). The record says "this agent still has work running"; it doesn't change whether the agent takes input.

The decision at the moment of delivery is mostly there already: hc send checks the state when it types, not before. It refuses a blocked agent, and with --if <status> it types only if the state is exactly that at that moment (otherwise status_mismatch, nothing typed). Queueing would be the missing piece. Since the record sits beside the agent's state, it doesn't change what hc send does.

What core lacked was a way to get this information in at all. Claude Code's hooks run with no terminal, so they can't write OSC 7501. herdr-core#81 adds hc report, which applies a 7501 report for such a process. It goes through the same parser as screen output, and there's no agent-specific logic in core. With it, a Claude Code Stop hook reports the bg record while background shells run and clears it when they finish (refs herdr-core#42).

Once that's in core, herdr-app can use it without changing its defaults. The records are already in what mods get from terminals(), so a mod can show "at prompt, background work pending" as its own group and leave idle alone for automation. The one part a mod can't do is hold back the "done" sound and toast until the records end.