feat: native subagent & workflow observability by t3dotgg · Pull Request #5219 · pingdotgg/t3code

t3dotgg · 2026-08-02T06:59:02Z

Problem

When a thread spawns subagents, runs a workflow, or drives Codex collab agents, the UI showed nothing useful: subagent tool calls and narration interleaved anonymously into the parent chat, progress ticks spammed the work log, background shells masqueraded as agents, the sidebar showed no status once the turn settled, and Stop only killed the parent turn while the fleet kept burning tokens.

Spec (final, decisions locked): https://n0hbggyouhn1.postplan.dev

Solution

Surface agents using only native provider emissions on the current orchestrator — no dependency on orchestrator v2 (#2829), zero migrations, zero new tables. Widened task.* activity payloads ride the existing event-sourced activity path; a client-side fold in client-runtime derives orchestration-v2-shaped subagent state (field names match #4779, so the v2 merge is a mapper swap).

Server

Contracts: additive TaskAgentLinkage on all task payloads (role, model, workflow name/phases, run handles, output file, owning agentId), new task.updated event, typed usage, tool attribution (agentId/parentToolUseId)
ClaudeAdapter: carries previously-dropped fields, handles task_updated, resolves parent_tool_use_id on tool events, keeps subagent narration out of the parent transcript (leak + Working-timer-reset fix), attributes subagent-internal shells to their owning agent, defensive workflow_progress parse, Workflow run handles
Codex: registers multi-agent-v2 children from thread/started/subAgentActivity (root-thread guard from live probe), intercepts child notifications, synthesizes the same task.* lifecycle (idle = resumable, cumulative usage, real names from agentPath)
Stop-everything: interrupt stops every live Claude task (Query.stopTask) and interrupts every live Codex child turn before the parent turn
Sidebar liveness: ThreadBackgroundLivenessService (in-memory, no persistence) exposes backgroundLiveness: working | monitoring on the thread shell — fleets read Working, watch loops read Monitoring
orchestration.getWorkflowScript RPC with TOCTOU-safe containment (open-then-verify inode, realpath under ~/.claude/projects, .js-only, size cap)

Web

Agents right-panel surface (the only roster): live workflows as bordered sections with a phase rail (per-phase segments with member status dots) and collapsible phase sections (live open, done collapsed); flat agent rows (no unfold); settled runs collapse to one line under "Earlier"; {} script opens a read-only script view
Spawn CTA row in chat: one anchored row per workflow run / direct-spawn batch, exempt from turn folds and overflow, membership pinned at first row (parallel-batch fix), coordinator status authoritative for workflows
Quiet timeline: agent-attributed tool rows re-homed to the panel, timelineBypass rows fold into the CTA, background shells stay ordinary work-log rows
All in-flight states present as Working (monitoring-pill rule); idle presents as settled

Mobile: same quiet-timeline fold; task.completed kept as terminal signal.

Verification

client-runtime: 30 fold tests (identity/activations, usage merges, bounds, cascade, nested agents); web: 1772 incl. quiet-timeline fixtures built from real persisted threads; server: adapter/ingestion/liveness/script-containment suites incl. a symlink-escape test and a stop-everything test
Live-tested over multiple rounds: Claude direct spawns + workflows (incl. 10-parallel), Codex collab fleets (10 agents), rerun workflows, monitoring threads — each round's findings fixed against exported wire/DB data

Remaining gaps

Codex fixtures should be generated from the captured wire logs (three schema-vs-wire divergences were found live)
Settled Codex rows show "assistant message" filler instead of a result summary
Script viewer is plain <pre> (no Shiki)
Mobile has only the timeline fold, no Agents sheet yet
Deferred by design: approval deep-links, transcript drill-in, forwardSubagentText/agentProgressSummaries off

🤖 Generated with Claude Code (Claude Fable 5)

Note

Add native subagent and workflow observability with an Agents panel, background liveness banner, and spawn CTA rows in the chat timeline

Adds a new Agents right panel surface (AgentsPanel.tsx) showing live status, elapsed timers, and activity text for each subagent or workflow member.
Introduces a background liveness banner in the chat view with a pulsing dot and Stop button when background work is detected via the new ThreadBackgroundLiveness service; sidebar rows show 'Working' or 'Monitoring' pills accordingly.
Adds spawn CTA rows to the chat timeline that collapse multiple subagent/workflow lifecycle entries into a single row with status, token count, and an affordance to open the Agents panel.
Enriches the Claude and Codex adapters with task.updated and tool.progress event emission, stable per-task activity IDs, agent linkage fields (agentKind, agentId, toolUseId, runHandles), workflow member coalescing, and interrupt-all-live-tasks behavior on turn stop.
Adds a getWorkflowScript WebSocket RPC backed by a TOCTOU-safe reader that serves .js files under ~/.claude/projects up to 256 KiB with structured error reasons.
Risk: RIGHT_PANEL_STORAGE_VERSION bumps from 7 to 8, invalidating persisted right panel state for existing users; task.progress activity IDs change from event-scoped to stable per-task IDs, which may affect clients that stored or compared those IDs.

^{Macroscope summarized f7673f3.}

Dispositions (review round, explicit)

Spec divergence — accepted. The linked spec predates seven rounds of live testing. The rich inline workflow card, live strip, and expanded activity rows were built, tested live, and deliberately replaced by the single spawn CTA + Agents panel ("too much at once" — live-test decision). The spec link stays for design history; this description is the source of truth for what ships.
Mobile — accepted tradeoff for this PR. Mobile gets the quiet timeline and preserved terminal signals (Claude task.completed, Codex terminal task.updated, nested-agent terminals) but no Agents surface yet. Live fleets are less visible on mobile until they settle. The read-only mobile Agents sheet is the tracked fast-follow.
Script RPC scope — accepted with containment. getWorkflowScript takes threadId but does not yet verify the path against that thread's recorded runHandles (that registry is Orchestrator v2's read model; this PR is zero-migration by design). Access is bounded to the local paired user's own ~/.claude/projects (realpath re-containment, .js-only, TOCTOU-safe open, size cap). Thread-scoped verification is a small follow-up once v2's projection lands.
Event-rate bound. Workflow member fan-out is coalesced by a material-transition filter (emit only when a rendered field changes), and progress activities upsert under stable thread-scoped ids — worst case per coordinator tick is now proportional to changed members, not fleet size.

Note

High Risk
Touches provider adapters, runtime ingestion, interrupt/stop paths, and Codex child-notification routing—security-sensitive file read RPC and behavior changes that can hide or mis-route live agent signals if classification drifts.

Overview
Adds end-to-end subagent and workflow observability on the existing activity stream: ingestion stamps agentKind and linkage on task.* / tool rows, uses stable thread-scoped progress ids so ticks upsert instead of flooding retention, and maps Claude task_updated plus Codex collabAgent/* into shared task.updated / bypassed terminal updates.

Server behavior changes: ThreadBackgroundLiveness (in-memory) drives backgroundLiveness: working | monitoring on thread shells; runtime ingestion records task lifecycle and clears on session.exited. Stop now stops live Claude tasks (stopTask) and bounded Codex child turn/interrupt before the parent. Claude drops subagent narration from the parent transcript, attributes tools via parent_tool_use_id, parses workflow_progress with member coalescing, and Codex registers v2 children with explicit routing (root self-activity guard, interception before legacy suppressor). New read-scoped getWorkflowScript RPC reads .js under ~/.claude/projects with realpath containment and TOCTOU-safe open.

Mobile mirrors the web quiet timeline: hide agent-internal background work but keep nested agent terminals and Codex terminal bypass task.updated rows; task rows collapse by taskId.

^{Reviewed by Cursor Bugbot for commit f7673f3. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

New Features
- Added an Agents panel showing live and completed subagent workflows, phases, status, usage, and activity.
- Added workflow script inspection with loading, truncation, and error states.
- Added Working and Monitoring thread statuses with live background-task counts and a Stop action.
- Added support for multi-agent collaboration, including nested tasks, progress, retries, and interruptions.
Bug Fixes
- Reduced duplicate and internal activity in the work log while preserving meaningful task progress.
- Improved task status, ownership, and usage reporting across providers.

…imeline) Surface Claude Code subagents/workflows and Codex collab agents in the UI using only native provider emissions. Zero migrations, zero new tables: widened task.* activity payloads ride the existing event-sourced activity path, and a client-side fold in client-runtime derives v2-shaped subagent state (field names match #4779 so the orchestration-v2 merge is mechanical). Server: - contracts: TaskAgentLinkage on all task payloads, new task.updated event, typed RuntimeTaskUsage, tool attribution (agentId/parentToolUseId) - ClaudeAdapter: carry subagent_type/workflow_name/tool_use_id/outputFile, handle task_updated (was dropped), attribute subagent tool events via parent_tool_use_id, defensive workflow_progress parse, Workflow run handles - CodexSessionRuntime/Adapter: register multi-agent-v2 children from thread/started + subAgentActivity, intercept child notifications, and synthesize task.* lifecycle (idle=resumable, cumulative usage) [WIP: routing is probe-gated per spec] - ingestion: task.updated + agent-owned tool.progress persisted; wire-slim regression test proving agent fields survive to the client Web: - Agents right-panel surface (workflow phase groups, direct spawns, static status dots, DOM-write elapsed timers, expandable activity ring) - composer live strip + inline workflow run card (8-row urgency cap) - quiet timeline: one lifecycle row per agent (collapse by taskId), agent- attributed tool rows re-homed to the panel, timelineBypass rows suppressed Mobile: same quiet-timeline fold; task.completed kept as terminal signal. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

coderabbitai · 2026-08-02T06:59:09Z

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 39.08% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the primary change: native subagent and workflow observability.
Description check	✅ Passed	The description explains the problem, solution, UI changes, verification, tradeoffs, and remaining gaps, although it does not use every template heading.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

macroscopeapp · 2026-08-02T07:03:54Z

Approvability

Verdict: Needs human review

1 blocking correctness issue found. Diff is too large for automated approval analysis. A human reviewer should evaluate this PR.

^{You can customize Macroscope's approvability policy. Learn more.}

…w card Per live-test feedback the roster rendered three times at once (panel, card, strip). New rule: the Agents panel is the only roster. The chat gets one anchored CTA row per spawn batch (workflow run, or a turn's direct spawns): 'Kicked off N subagents · <workflow> — <phase> · N active · Σ tok — Open Agents'. Live status derives from the shared panel model at render time; the row freezes to past tense on settle. Strip and card components deleted. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Live-test round 2 fixes: - Shells/monitors/plan tasks no longer masquerade as subagents: taskType rides on every task payload (adapter linkage + ingestion allowlist) and the fold excludes non-agent task types from the roster. 'Run 12s stall' background shells stay in the ordinary work log. - The spawn CTA no longer says completed while a workflow is mid-flight: for workflow batches the coordinator's own terminal state is authoritative (dynamic spawns can make the known-member list momentarily all-settled). - Agents panel rows are flat status lines: the per-agent unfold (recent tool-call feed) is gone. The only expansion is run-granularity: settled workflow runs collapse to one summary line under 'Earlier', click to list members. Live workflows and direct spawns sort first in bordered sections with settled/total counts. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Rerun workflows looked invisible: the launching turn settles in seconds ('Worked for 8.9s') and turn-folding collapsed all its work entries — including the spawn CTA — while the fleet runs on in the background. CTA rows are now exempt from turn folds and pinned outside the '+N tool calls' overflow toggle, so a live run is always visible at its spawn point. Each rerun gets its own CTA row (grouping keys on the coordinator id, which is unique per run). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Live-test finding: statuses drifted (waiting/stalled agents alarming or reading wrong) while fleets ran. Adopts the monitoring-pill rule from the PR-monitoring design: one steady in-flight presentation. - Panel and CTA: pending/running/waiting all render as Working (sky, no amber); detail stays in the activity sub-line; footer shows one working count. Only settled states differentiate (completed/failed/stopped). - Fold: when a workflow coordinator settles, members that never received their own terminal row cascade to the coordinator's outcome (completed, or interrupted on failure) instead of reading as working forever. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Live-test: the CTA only appeared after the workflow finished. Two causes, reproduced against the exact persisted thread data: - workEntryIndicatesToolNeutralStatus swallowed spawn rows mid-run (they derive from task.progress, tone 'thinking' = neutral) — visible only once a terminal row flipped them to success. CTA rows are now exempt. - collapse-by-group let the newest progress tick's id/createdAt/turnId win, drifting the row to the bottom of the timeline mid-run. The group anchor (spawn point) is now pinned. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Live-test: a thread running a 9-agent workflow and a thread babysitting a PR both showed no sidebar status once their turns settled. The pill only reflected turn/session state. - Server: in-memory per-thread background liveness registry fed by the task lifecycle ingestion already processes (no persistence, no migration); exposed additively on the thread shell as backgroundLiveness: working | monitoring | null. - Vocabulary (per Theo): two states only. Agent/workflow fleets present as plain Working; Monitoring is reserved for watch loops (monitor tasks and turn-outliving background shells — PR babysitting, log tails) when they are the only live work. - Web: pill resolver and SidebarV2 status honor backgroundLiveness with the same recede treatment as Working (inbox-zero); Monitoring gets a steady label, no shimmer. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

macroscopeapp

Effect service conventions review: one clear violation (new shared mutable state held in a module global and consumed by two Effect services) plus one file-layout nit. Everything else in the changed Effect code (namespace imports from effect/* subpaths, per-session Map state inside Effect.gen, contract schemas) looks conformant.

^{Posted via Macroscope — Effect Service Conventions}

Live-test: plain Task-tool subagents vanished from the Agents panel and CTA. The SDK reports them as taskType 'local_agent', which the agent-type allowlist didn't anticipate — real agents were silently classified as background work. Classification is now a denylist (shell/local_bash/ monitor/plan are background; anything else, including future agent-flavored type names, is an agent). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

First live Codex probe (5 collab agents on gpt-5.6-sol) surfaced three gaps, fixed against the persisted wire data: - Children registered only via subAgentActivity (no thread/started with a spawn source), so no task.started ever formed and rows carried bare thread-id titles. subAgentActivity 'started' now synthesizes the task.started with agentPath-leaf naming. - Codex child rows are ALL timelineBypass, so the quiet-timeline filter suppressed every row before the CTA could form — a Codex fleet had no chat presence at all. Bypassed agent lifecycle rows now feed the CTA collapse (still max one row per batch); non-agent bypassed rows stay suppressed. - Idle now counts as not-live in the sidebar registry: an all-idle (resting, resumable) fleet no longer pins the thread at Working. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Live-test round 2 on Codex direct spawns: - Idle (resting, resumable) agents wore a sky dot and sat in the live section, reading as stuck in-progress after the work finished. Idle now renders muted and sorts with settled. - Progress rows carried the bare child thread id as title, clobbering the real name (math_one → UUID) from task.started. The runtime now stamps the registered child's identity (nickname/role/agentPath) on every synthetic collabAgent event, the adapter only emits title when it has a real name, and subAgentActivity registration derives a nickname from the agentPath leaf. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Live probe on 10 parallel collab agents: the wire emits subAgentActivity {agentPath: '/root', kind: interacted} about the ROOT thread during collab runs. Registration adopted the root as a child, so every subsequent root notification — including the final assistant message and turn/completed — was intercepted into the agent panel instead of the chat. The parent looked hung ('Working 5m') after all subagents finished, with its report riding an 'assistant message' row on the root's panel entry. Registration now refuses the session's root thread (by id and by /root path), and interception has a belt-and-braces root check. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… row Claude background subagents settle between turns, so their completion rows arrive under later synthetic turn ids (or none). Batch keying by each row's own turn splintered ten parallel spawns into a stream of 'Kicked off N subagents' rows (live thread 7ac7ef05: completions spread across 8 different turn ids). Membership is now decided once at the first row seen per taskId — task.started rows (which carry the true spawn turn) seed the batch and collapse into its CTA instead of being skipped. Repro test derives exactly one CTA with all 10 agents from the persisted thread export. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…nscript Two live-test findings with parallel Claude subagents, one root cause: even with forwardSubagentText off, the SDK forwards subagent-owned messages tagged parent_tool_use_id, and the adapter emitted them as parent conversation. - Subagent assistant snapshots became interleaved leak messages ('sleep ran successfully…') AND spawned a synthetic turn per completion — which is also why the Working timer kept resetting to 0: each synthetic turn restarted the elapsed clock. Subagent-owned assistant messages now only advance the resume cursor. - Subagent-owned text/thinking stream blocks wrote into the parent transcript; they are now dropped (tool_use blocks still flow, with agentId attribution, for the quiet-timeline re-homing). Subagent results still reach the UI through the task.* lifecycle (task_notification summaries) — the panel loses nothing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

These seven files were the only content that existed solely on t3x/loop-supervisor. That branch was cut from a 2026-07-28 merge-base and has since fallen far enough behind that merging it would delete infra/t3x-update-relay and docs/t3x/agents — so it is being deleted rather than landed, and the research would have gone with it. What is worth keeping is not the proposal but the evidence under it: SUBAGENTS.md reproduces Claude Code's subagent wire protocol event-for-event against real captures, and RESEARCH.md / OPTIONS.md record a 4-design, 12-judgement panel with the codebase reads that killed three of the four. DESIGN.md now opens with a status banner saying the feature was never built, and naming the two upstream changes (pingdotgg#5219, pingdotgg#3638) that have since moved under it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Upstream's pingdotgg#5219 (native subagent & workflow observability) and pingdotgg#5677 (stop the reaper killing live background subagents) put two shared registries behind the projection snapshot query: ThreadBackgroundLivenessService and ThreadPlanProgressService. The fork's crash-recovery reconciler test builds its own layer rather than reusing orchestration/runtimeLayer.ts, so it did not pick them up and failed typecheck with an unfilled Layer context. Provided rather than provideMerge'd — nothing in this test reads the registries directly, so they need satisfying, not re-exporting. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

These seven files were the only content that existed solely on t3x/loop-supervisor. That branch was cut from a 2026-07-28 merge-base and has since fallen far enough behind that merging it would delete infra/t3x-update-relay and docs/t3x/agents — so it is being deleted rather than landed, and the research would have gone with it. What is worth keeping is not the proposal but the evidence under it: SUBAGENTS.md reproduces Claude Code's subagent wire protocol event-for-event against real captures, and RESEARCH.md / OPTIONS.md record a 4-design, 12-judgement panel with the codebase reads that killed three of the four. DESIGN.md now opens with a status banner saying the feature was never built, and naming the two upstream changes (pingdotgg#5219, pingdotgg#3638) that have since moved under it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Upstream's pingdotgg#5219 (native subagent & workflow observability) and pingdotgg#5677 (stop the reaper killing live background subagents) put two shared registries behind the projection snapshot query: ThreadBackgroundLivenessService and ThreadPlanProgressService. The fork's crash-recovery reconciler test builds its own layer rather than reusing orchestration/runtimeLayer.ts, so it did not pick them up and failed typecheck with an unfilled Layer context. Provided rather than provideMerge'd — nothing in this test reads the registries directly, so they need satisfying, not re-exporting. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

A fresh two-axis review plus an adversarial re-verification of every [V] claim found three that did not survive contact with the tree, one of them a design hole an implementer would have built. - The [60, 3600] clamp belongs to ScheduleWakeup alone. session_crons also carries CronCreate entries, which take an arbitrary 5-field expression with no hour bound, so "the exposure is bounded without a second rule" was wrong: a recorded `0 9 * * *` stands T3 down for up to 24h. Deference is now capped at the loop's own deadline, since past it there is nothing left to defer to. Added by review, and open beside Q1. - wakeGraceMs ~90s was the wrong half of the jitter model. 90s is the one-shot *early* jitter; the late jitter is up to 10% of period, max 15 min. Grace is now derived from the recorded entry, so a healthy jittered wake no longer fires wake_lost. - D2's evidence is retracted, its conclusion kept. Four closers exist and handleResultMessage's is unconditional, and pingdotgg#5219 retired the subagent -> synthetic-turn path nine days before this was written. Re-anchored on the session reaper, which refuses to reap a thread with an activeTurnId. Also: settingsSearch.ts is ~+13, not ~+4 (each search item is a 5-6 line object literal), so phases 1-4 cost ~16 lines rather than ~7 — the row counts are unchanged. The 08-18 sync moved the merge-base to cebac35, and the headline 53 files / +2590/-1042 only holds against it. One assumption got promoted: the Stop hook does deliver session_crons, spread unconditionally into both Stop and SubagentStop, [] when empty. That was PLAN's top-listed falsifier. It also turned up an undocumented 1000-char truncation on the prompt field, now covered by a test case. Guard #15, the run digest, and loop_status's narrowing are now declared as divergences rather than decided in silence. build-report.mjs documents the full build-then-fmt pipeline, which is what actually reproduces the committed report. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Native subagent observability (#5219), wired per its spec's v2 merge plan: - getWorkflowScript RPC re-homed onto the v2 WS surface (contracts, rpc group, ws handler, auth scope, client atom). - AgentsPanel fed by the spec's mapper swap: projectedSubagentsToRuntime maps orchestration-v2 subagent entities into the panel model; deriveAgentPanelModel's v2Projection leg is now live and the v1 fold never runs. Agents surface wired into ChatView + RightPanelTabs. Other ports and reconciliations: - Shell reconnect-loop fix (#5561) ported into the v2 shell sync (same-session resubscribes resume from the in-memory cursor), with the cursor-resume regression test adapted to v2 fixtures. - Mobile end-follow latch (#5566) ported onto the v2 ThreadFeed. - Claude ede_diagnostic interrupt classification (#5557) ported into ClaudeAdapterV2 (aborted_tools/aborted_streaming => interrupted; CLI telemetry never becomes the failure banner). #5559 needs no v2 port (unknown system subtypes are already ignored). - Plan sidebar removed from the v2 ChatView/ChatComposer per main's plans-fold-into-chat rework (#5558); rightPanelStore stays at main's surface set. - SettingsPanels rebuilt as main's refactored version plus the branch's composer-context setting; sidebar snooze respects the time format (#4438 follow-through). - v1-only leftovers deleted: zombie v1 adapters/ingestion/tests the v2 rewrite removes, the v1-bound transfer-budget CI harness (#5350, needs a v2 rebuild), and main's v1 client pagination machinery (#5493 client side; the 037 keyset migration is kept — server-side v2 windowing is a follow-up). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:XXL 1,000+ changed lines (additions + deletions). labels Aug 2, 2026