feat: native subagent & workflow observability

[t3dotgg]

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.

[coderabbitai]

🚥 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

• X
• Mastodon
• Reddit
• LinkedIn

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

[macroscopeapp]

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.}

[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}