Truthful agent lights: classify live background work at turn end, and expire stale active glyphs

[x9x9x9x9x9x91]

The stock Claude hook package maps Stop → completed --auto-reset
unconditionally. That makes the sidebar glyph lie in three common agent
workflows:

1. Turn ends, work continues. A session that dispatched background work
   (a test/CI run via a background tool call, or a second agent as a worker)
   goes green at Stop while the work is still running. After the row is
   visited once: no glyph at all, indistinguishable from idle.
2. Agent dies (or goes idle), glyph stays. A killed agent leaves its last
   pushed active pulsing forever; nothing ever times out.
3. Model-thinking vs machinery vs queued. A 30-minute gates run, the model
   reasoning, and a lane parked in a lock queue all look identical
   (active), so "is it stuck, testing, or just waiting its turn?" can't be
   answered from the sidebar.

We run a hook-package extension on 0.19.1 that fixes all three across ~20
concurrent agent sessions; posting to ask whether any of it is
upstream-worthy, and in which shape.

Turn-end classifier (Stop hook). Claude Code tool commands — foreground
and background — run under a recognizable wrapper (zsh -c source …/shell-snapshots/snapshot-…) that is a child of the agent process, while MCP
servers and harness helpers are direct children without it. One ps -axo pid,ppid,command pass at Stop classifies what is still alive under the agent:
a wrapper subtree containing another agent binary → active --blink (workers
still running); a subtree doing real work → active --color '#4A9EFF' --shape square (machinery); a subtree whose only leaves are wait-shaped processes
(sleep/flock/tail/grep — a lock queue, a poll loop, a log monitor) → the same
blue with --shape triangle (the closest the shape set has to a "queued"
arrow), so waiting reads differently from executing; nothing → completed --auto-reset as today. The per-call tint/shape channel turned out to be
exactly right for this.

Machinery paint during the turn (PreToolUse). A small matcher paints the
blue square when the command about to run is gate/test-shaped, so a long CI
run reads differently from the model thinking. The next PostToolUse restores
the pulse.

Ownership guard. A worker agent spawned from inside a session (headless
claude -p, a second CLI agent) inherits the spawner's AGTERM_*
environment, so its own Stop/SessionEnd hooks repaint the SPAWNER's row — we
found seven sessions sharing ids live, with a coordinator's row going green
mid-run because a finished worker's Stop fired against it. Fix: the status
hook walks up to the calling agent and stays silent when that process has no
controlling terminal (ps -o tty= says ??); pane-attached agents always
have one. This guard belongs in the stock hook package regardless of the rest.

Staleness sweeper. A launchd job (2 min) enforces "no glyph = idle" in
both directions: agent pid dead and hooks dark → idle; agent alive but zero
work subtrees and no hook fire for 25 min → idle (the idle-at-prompt lie);
live work found under a glyph-less row → re-light it grey/square/triangle. We
first shipped a cputime-probe "stuck" detector and retired it the same day:
measured over 3s windows, a wedged agent process is indistinguishable from a
healthy idle one (runtime timers keep ticking), so process-CPU is a dead end —
honest stuck detection needs progress signals, not process state.

Questions:

• Is the Stop classifier something you'd take into the stock hook package, or
  would you rather see the whole thing as a cookbook recipe? Happy to PR
  either shape.
• The ownership guard is small, self-contained, and fixes silent cross-session
  repaints for anyone who spawns agents from agents — want it as a standalone
  PR to the stock hooks even if the rest stays a recipe?
• The sweeper exists only because a pushed status is trusted forever. The root
  fix may be app-side: agterm could dim/expire an active glyph that hasn't
  been re-set for N minutes (configurable, off by default). Hooks already
  re-push active on every tool event, so a live session would never decay.
  Would you take an issue/PR in that direction?

Scripts are small bash, BSD-userland clean, and degrade to the stock behavior
outside agterm.

[umputun]

all three are separate calls, so taking them one at a time.

the classifier: cookbook. same answer as #332 and #382, with two agterm-specific reasons on top of the usual one.

first, an installer change wouldn't reach you or anyone else who already installed: mergeClaudeSettings skips an event when any entry there already invokes the wrapper, and there is no refresh path on the Claude side the way refreshManagedCodexBlock gives Codex one. So a changed Stop mapping in the table only affects fresh installs, and everyone else keeps completed --auto-reset in their settings.json until they hand-edit it. A hook change that reaches new users only is worse than no change.

second, --color and --shape are per-call overrides of a user preference, and the override wins over the configured value. Settings > Agent Status has a color and a shape per state, and the docs sell shape as the way to tell states apart without depending on hue. If the stock hooks start painting blue squares and triangles for sub-states of active, someone whose blocked shape is a triangle now reads "queued" as "blocked", and he opted into neither. That vocabulary is fine in a recipe the reader chooses, not in the default package.

the rest is the usual bar. The discriminator is Claude Code's own snapshot wrapper shape, undocumented and free to move, and the leaf-shape rule reads rg over a big tree as waiting and tail -f on a build log as work. In a recipe that is a Limits paragraph and a version pin; in the installer it is a notarized release every time upstream changes something. Write it up with the wrapper dependency stated plainly in Limits, per cookbook/CONTRIBUTING.md.

the ownership guard: the bug is mine, the tty test is not the fix. a cross-session repaint is a defect and it belongs in the package, same class as #199. But ps -o tty= is wrong in both directions. A worker under script, expect or unbuffer keeps a tty and still repaints the spawner, and anything legitimately headless that wants to report goes silent with no way to tell: ssh without -t, a LaunchAgent, a batch run pointed at a dedicated session. On top of that agterm-agent-status.sh is shared by Claude, Codex, Pi, OpenCode and three recipes, so a guard there makes all of them quieter to fix one spawn pattern.

the bundled OpenCode plugin already solves this without asking the OS anything: it tracks the agent's own session ids and fires completed only when that set empties, so a subagent's idle cannot paint completed onto a still-busy parent (#289). Compare against that before you write the PR. If a Claude-side guard is still the answer after that, I want it in a Claude-specific layer, not in the shared wrapper.

expiry: no, and the reason is your own case 1. no hook for N minutes is not liveness. The package installs no PreToolUse, so a 30 minute foreground gates run emits nothing between the tool starting and its PostToolUse. Any N shorter than the longest tool call kills an accurate glyph, and expiring to idle draws nothing at all, which is the same "indistinguishable from idle" you object to in case 1. That trades a stale light for a wrong one, and adds the app's first repeating timer to do it.

what is actually missing is read-back: the tree node carries status, pane, blink, color and shape but no timestamp, so your sweeper has to keep its own state to know how old a glyph is. Send an issue for statusChangedAt on the node and I will take it. One field, no setting, no policy in the app, and it turns the sweeper into a tree --json one-liner. The per-pane foreground argv (#358) already answers "is anything running here" from the app's own descent, which beats a ps scan for the dead-agent half of it.

[x9x9x9x9x9x91]

All three land. Recipe it is — I'll write the classifier up per cookbook/CONTRIBUTING.md, snapshot-wrapper dependency and the leaf-shape misreads stated plainly in Limits, and keep the shape/color vocabulary as something the reader opts into.

On the guard: agreed the tty test fails both ways once you name script/expect and the deliberately-headless reporters. I'll do the comparison against the OpenCode plugin's session tracking before writing anything — one observation going in: its state is in-process (one plugin instance sees every session of that OpenCode process), while my failure case is separately spawned claude -p processes that share nothing, so the Claude-specific layer probably ends up testing process ancestry rather than session sets. Whatever survives the comparison comes as a PR against a Claude-specific layer, not the shared wrapper.

One aside, since it frames what the recipe will be: the running system already enforces your invariants rather than conceding them. Nothing expires on hook silence — the idle-clear fires only when an independent process scan shows zero work under the agent, stuck detection reads transcript progress rather than hook gaps, and the color/shape vocabulary lives in an opt-in layer, not the stock hooks. So the recipe describes a design field-tested against the failure modes you named, not a proposal.

statusChangedAt: filed as #460.

[x9x9x9x9x9x91]

Comparison done — measured on a live estate (~20 concurrent sessions), chains and timings, not reasoned from memory. Three results.

The OpenCode mechanism doesn't port, but its principle does. The plugin's three Sets live in one Node heap, and one plugin instance sees every session of its OpenCode process — parent and subagents publish onto the same bus, so completed can be gated set-wide. Claude hooks are separate short-lived OS processes fired by separate agent processes: no shared heap, and nothing in the spawner ever observes the worker. The gate is also answering a different question — timing within one owner ("hold completed until the last of us is done"), not ownership ("this reporter doesn't belong to this pane at all"); even a perfect port would still let a worker's active --blink and blocked through, since only completed is gated. What transfers is the principle: decide from the agent's own identity/topology, never from OS terminal state.

The guard that survives it: count agent ancestors, in a Claude-specific shim. New agterm-claude-status.sh beside the Codex adapter, delegating argv verbatim to the shared wrapper — the wrapper itself untouched. The hook walks its ppid chain toward the pane; exactly one agent binary found (its own) → pane's agent, report; a second one → another agent spawned mine, stay silent. Measured against every counterexample you named: script/expect/unbuffer add a pty hop but don't break parentage, so the spawner is still in the chain → correctly silent (the case the tty test false-reported); ssh without -t / LaunchAgent / a batch run deliberately pointed at a dedicated session has no agent ancestor → correctly reports (the case it false-silenced). One hole, named rather than discovered later: a worker that outlives its spawner reparents to launchd and the chain evaporates — the guard fails OPEN there, i.e. today's behavior, which is the inverse of the tty test's silent fail-closed. Cost ~25 ms per fire on a 978-process machine doing the walk per-hop (a full ps -axo snapshot is ~2× that, so the walk is the cheap form).

The finding that shapes the PR: your classifier objection applies to a naive shim too. mergeClaudeSettings skips any event already invoking the wrapper and the Claude side has no refreshManagedCodexBlock counterpart, so a shim that only changes the generated entries reaches fresh installs only — the exact defect you named. The PR therefore carries a Claude-side migration, scoped to be safe: rewrite an entry only when its command is byte-exactly what the installer generated, swapping the wrapper path for the shim path; hand-edited entries untouched; migrate-once / idempotent / leave-customized-alone tests beside the existing merge tests. I wouldn't open it without that part.

Long-term there's a cleaner answer that deletes the whole heuristic: foregroundPid (and splitForegroundPid) on the tree node. #358 already resolves the pid before rendering argv, so it's plumbing an existing number through the protocol — and with it the shim reduces to "does the pane's foreground pid sit in my ancestry", no agent-name table, no broken-chain hole. Want that as an issue in the same family as #460?

Unless you'd rather sequence it differently, the PR comes as: shim + installer wiring + migration, migration as its own commit so both parts read separately. (One correction to my own filing while I'm here: the stock package installs no SessionEnd hook — the repaint comes from Stop plus the worker's UserPromptSubmit/PostToolUse fires; SessionEnd was our local extension.)

[x9x9x9x9x9x91]

Guard PR is up: #461 — the shape from the comparison above (adapter + byte-exact migration + hermetic script tests), shared wrapper untouched. The classifier recipe follows separately once it clears review.

[x9x9x9x9x9x91]

And the classifier recipe: #462. That's all three calls from your reply acted on — recipe (#462), guard in a Claude-specific layer with the migration (#461), statusChangedAt as an issue (#460).