v0.3.0 — read-only activity viewer

Pivot to a read-only activity viewer. v0.1/v0.2 were an orchestrator (embedded MCP server that spawned, waited on, verified and cancelled agents). That role is now better served by Claude Code natively, so v0.3 re-focuses on the lasting value — observability. It watches the agents Claude Code already runs, via its activity hooks, and never spawns or drives them.

The orchestrator line is preserved and remains installable at tag v0.2.0.

Highlights

• Hooks-driven ingester (SubagentStart/SubagentStop/Stop/SessionEnd) → live sidebar board grouped by project · session · directory.
• Liveness reconciliation (pulse / idle / honest duration) and orphan recovery.
• Detail panel reads model + tokens + context% from the session transcript on demand.
• Completion toast; session scanner + resume.

Removed

• Embedded MCP server + all orchestration tools, the @anthropic-ai/claude-agent-sdk runner, bearer auth, agent-cancel UI, and verification mechanisms D+A. With the runner gone, the .vsix drops from ~74 MB to ~207 KB.

Install

Download the .vsix below, code --install-extension claude-orchestrator-0.3.0.vsix, reload, then run Claude Orchestrator: Install global activity hooks once.

Full notes in CHANGELOG.

v0.2.0 — Mecanismo D + A safety net

Mecanismo D + A safety net — second v0.2 milestone. Closes ticket #1 of the v0.2 backlog.

What's new

• Mecanismo D (Structured exit) — agents emit a JSON block at end of turn with decisions_made_without_consultation + uncertainties. The orchestrator auto-promotes status to needs_review when those are non-empty. Zero runtime cost — only changes the prompt.
• Mecanismo A (Critic Haiku post-fan-in) — after wait_for_agents, one Haiku per terminal agent reviews the working-tree diff and flags concerns. Toolset allow-listed to Read/Bash/Grep/Glob (no Write/Edit). Real findings (severity high/med) promote to needs_review; synthetic flags from parser/timeout fallbacks stay visible for diagnostics but do not promote.
• New setting claudeOrchestrator.verification: 'none' | 'structured' | 'critic' | 'both' | 'human-review'. Default 'structured' (D-only). Enable 'both' for migrations and assertion contract changes (adds ~$0.002–$0.05 per agent in Haiku critic cost).
• VerificationBadge UI in the RECENT card: verifying… (italic), ✓ Haiku OK (green), ⚠ Flagged (orange).
• 5th terminal status needs_review extends AgentStatus. Centralized via TERMINAL_STATUSES SSoT + isTerminalStatus() predicate.

Fixes during smoke

• git diff <headBefore>..HEAD returned empty because agents mutate working tree without committing — switched to git diff <headBefore> (working tree vs commit).
• Synthetic low-severity flags from infra failures (critic_timeout, critic_no_output, etc.) caused false-positive promotions — severity filter restricts promotion to high/med only.
• emitStatusChange invariant gap: needs_review was missing from the "once terminal, never back to running" guard — migrated to isTerminalStatus().

Stats

• +24 tests in exit-schema.test.ts (parser + prompt content + tool allow-list)
• +24 tests in bridge.test.ts (verification flows + isTerminalStatus + readGitHead + captureCriticDiff async)
• 414/414 passing (was 358 at v0.2.0-pre.1)
• ~700 LOC in bridge.ts touched / +450 LOC new in exit-schema.ts

Validated

Full smoke E2E with adversarial flip prompts:

1. Mecanismo D caught an honest agent declaring decisions_made_without_consultation for an assertTrue → assertFalse flip.
2. Mecanismo A caught the same flip via critic Haiku review of the diff (4 findings: 1 high + 2 med + 1 low).
3. Benign helper task (_make_admin_user()) terminated done with critic_findings: [] — calibration of the critic prompt prevented over-eager false positives on additive changes.

Full CHANGELOG: CHANGELOG.md

Install

Download claude-orchestrator-0.2.0.vsix below and:

```bash
code --install-extension claude-orchestrator-0.2.0.vsix --force
```

Or via VS Code palette: Extensions: Install from VSIX...

After install, reload the window and verify /mcp shows claude-orchestrator: Connected.

v0.1.0 — first public release

[0.1.0] — 2026-05-27

First public release. The extension exposes an embedded MCP server with 5 tools, a live kanban dashboard, real cancel, long-poll fan-in, session resume, and a detail panel — all driven from any external Claude Code chat.

Added

MCP server

• HTTP server embedded in the extension host, listening on http://127.0.0.1:39127/mcp.
• Bearer token auth (256-bit random, persisted in VS Code Secret Storage, timing-safe comparison).
• Auto-register in ~/.claude.json on activation (merges with existing MCP servers, atomic write, idempotent). Opt-out via claudeOrchestrator.autoRegisterMcp = false. Palette command Claude Orchestrator: Register MCP in Claude Code re-runs the merge manually. Manual claude mcp add-json fallback still printed to the output channel on every activation.
• DNS rebinding protection (enableDnsRebindingProtection: true, restricted allowedHosts).
• Fresh McpServer + StreamableHTTPServerTransport per request to dodge a SDK bug (_streamMapping leak in stateless+JSON mode).

MCP tools (5)

• spawn_agents — spawn 1–8 parallel Claude Code agents per call. Per-task prompt, cwd (absolute), optional name / model / priority. Returns {batchId, agentIds}. Uses the official @anthropic-ai/claude-agent-sdk with toolset preset claude_code and user-level skills + memory inheritance.
• wait_for_agents — long-poll fan-in: blocks until all agent_ids reach a terminal state (done / failed / cancelled) or timeout_sec elapses (default 300s, max 1200s). Returns {results, pending, timed_out}. Event-driven internally (no busy polling).
• list_agents — registry snapshot of live + recent terminated agents.
• get_agent_log — ringbuffer (max 1000 entries FIFO) per agent. Supports since for incremental pagination.
• cancel_agent — wrapper over the bridge's AbortController. Idempotent ({cancelled: false} if the agent already terminated).

Dashboard (Vue 3 + Pinia + Tailwind v4 webview in the VS Code sidebar)

• Three live kanban sections: NOW PLAYING (running), UP NEXT (pending), RECENT (terminal, last 24h grouped by lifecycle).
• Project groups inside each section, derived from cwd vs claudeOrchestrator.projectsRoot + workspace folders.
• Project lifecycle states: active (green dot), idle (<24h, ring), inactive (≥24h, ring + opacity).
• Atoms: StatusDot (with optional pulse + halo), ContextBar (live tokens, color by threshold), ModelBadge, PriorityPill, FailedBadge.
• Project selector toolbar (dropdown — All projects default, filter to a single project).
• Standalone card variants for single-project views.
• Past sessions integration: scanner reads ~/.claude/projects/<encoded>/*.jsonl and renders past sessions per project with a Resume button.

Detail panel (custom editor tab)

• Custom WebviewPanel in an editor tab, opened by clicking a card body in the dashboard.
• Live LogStream rendering thinking (dim italic), tool_use (IN block), tool_result (OUT block with is-error indicator), text (paragraph), usage (pill).
• Auto-scroll with requestAnimationFrame throttle.
• Multi-webview broadcast in the bridge: sidebar + detail panel cohabit; targeted hydrateLogs(agentId, targetWebview) avoids re-serializing 1000 entries to the sidebar.
• Single-instance policy: opening a different agent disposes + recreates the panel (multi-instance is on the v0.2 backlog).

Cancel

• X button in each running card (sidebar + detail panel both cancel).
• AbortController plumbed from card click → scanner-controller → bridge → AgentRunner → SDK.
• Optional confirmation modal (claudeOrchestrator.cancelConfirm).
• cancel_agent MCP tool also exposed for chat-driven cancel.

Session resume

• Scanner walks ~/.claude/projects/<encoded>/*.jsonl with mtime cache + JSONL parser (no synchronous git forks per session — branch read from header).
• Heuristic project derivation handles edge cases: workspace = parent folder (e.g. ~/git18 with sessions in ~/git18/docs/<project>/), conversational prompts without file paths, etc.
• Resume in chat (default — uses vscode://anthropic.claude-code/open?session=<id> URI handler with workspace-cwd guard) or in a new terminal (claude --resume <id>).
• Empty state for projects with no agents and no past sessions.

Status bar

• Bottom-right item: $(rocket) N agent[s] while running > 0.
• Auto-hides when count = 0.
• Click → focuses the dashboard sidebar.

Completion notifier

• Toast on terminal status (done / failed / cancelled).
• failed uses showWarningMessage (warning icon); others use showInformationMessage.
• Open detail action button → opens the detail panel for that agent.
• Toggle via claudeOrchestrator.notifyOnComplete (default true).

Model selection

• Per-task model in spawn_agents (sonnet, opus, haiku).
• Tool description nudges the chat model to ask the user when not specified, especially before expensive long-running tasks.
• Setting claudeOrchestrator.defaultModel for the fallback when model is omitted.
• Real model id captured from SDKSystemMessage.init.model (e.g. claude-sonnet-4-5-20251022) and pretty-printed in ModelBadge (Sonnet 4.5).
• QuickPick on the palette command Claude Orchestrator: Test Agent.

Context bar

• Live tokens captured incrementally from SDKAssistantMessage.message.usage on every turn (not just on final result).
• contextTokens = input + cacheRead + cacheCreation — matches the percentage shown in the bar (previously inconsistent because most context travels via prompt cache).
• Separate tokensUsed field preserved as the billable per-turn cost (without cache reads).

Defensive caps

• claudeOrchestrator.maxAgentRuntimeSec (default 2000s) — hard cap on agent lifetime, bridge cancels with reason=max_runtime_exceeded. Race-safe against manual cancel.
• claudeOrchestrator.stuckDetectionSec (default 60s) — if a running agent emits no events for N seconds, wait_for_agents flags suspected_stuck=true in pending. Does not cancel — the chat decides.

Configuration (10 settings)

projectsRoot, scannerRefreshSec, resumeConfirm, cancelConfirm, notifyOnComplete, autoRegisterMcp, defaultModel, resumeIn, maxAgentRuntimeSec, stuckDetectionSec. See README.md for the table.

Test suite

• 287 unit tests across the extension host + webview (vitest + happy-dom + @pinia/testing).
• Coverage includes MCP schemas, bridge state transitions, scanner edge cases, project derivation heuristic, log ringbuffer, race conditions in cancel + max-runtime, atom variants, store getters.

Known caveats

• Bearer token in the output channel. The token is printed plaintext on activation to make claude mcp add-json setup one-shot. It's stored encrypted in Secret Storage between sessions, but anyone reading the output channel (or a screenshot of it) sees the token. Don't share output-channel screenshots publicly. A Copy MCP setup command with redacted display is on the v0.2 backlog.
• Context window can climb past 50–80% while cost=$0. This is Anthropic's prompt caching at work — cache reads are ~10× cheaper but still occupy tokens. Feature of the SDK, not a bug of this plugin.
• No MCP push for fan-in. We use wait_for_agents long-poll, not MCP push notifications. Reason: Claude Code 2.1.x ships with the tasks/* handlers internally but doesn't advertise the capability in the MCP handshake, and --channels push is blocked by Anthropic's org policy. Long-poll aligns with SEP-2663 (merged 15 May 2026, also polling-based). Migration to native push is ~30 LOC when upstream enables the capability.
• MCP tool selection requires explicit prompting. As of May 2026, Claude Code's model selection tends to prefer native Bash/Task over custom MCP tools unless the user names the tool in the prompt. See README.md → Usage for a working prompt template and the recommended user-level CLAUDE.md directive.
• Single detail panel instance. Opening a different agent's detail disposes the current panel and opens a new one. Multi-instance with cap + LRU is on the v0.2 backlog.
• No observability for chat-caller agents. The dashboard shows only agents this plugin orchestrated (via spawn_agents). Task subagents and Bash run_in_background invocations from the calling chat are not visible. A FileSystemWatcher over ~/.claude/projects/ is on the v0.2 backlog to complement.
• Large .vsix (~75 MB). The bundled @anthropic-ai/claude-agent-sdk ships a native claude CLI binary (~227 MB pre-compression) that the extension invokes at runtime. This puts the packaged .vsix above the 50 MB Visual Studio Marketplace limit, so this release is distributed via GitHub Releases only. A v0.2 task tracks bundling/lazy-install strategies to slim the package for Marketplace eligibility.
• First-run scan can take 60–90s. On first install (or after clearing globalState) the scanner cold-reparses every .jsonl in ~/.claude/projects/. With 150+ sessions across many projects, expect 60–90s before the dashboard fills with All projects (N). Subsequent activations hit the mtime cache and complete in ~25s. The sidebar currently does not show a "Scanning…" indicator during the cold pass — that polish is on the v0.2 backlog. Watch the output channel for [scanner] scan complete (startup) projects=N sessions=M.
• No "Scanning…" indicator in the sidebar during cold scan. The dashboard simply shows All projects (0) and "No agents yet" until the first scan finishes. Watch the output channel if you want progress. A proper sidebar overlay is on the v0.2 backlog.