Cost, Observability & Orchestration Gotchas

A single subagent is essentially free to reason about: it does heavy work in an isolated window and hands back a summary, so your main context — and your bill's growth — stays bounded. The moment you coordinate many agents, that intuition breaks, and the single number that predicts your spend is how many full context windows are alive at once.

Each paradigm sits at a different point on that curve:

The key contrast is workflows vs. teams. A workflow can spawn hundreds of agents, but their intermediate results live in script variables outside your context window — only the final verified answer lands in your session, so you don't pay context for every agent's chatter. An agent team is the opposite: each teammate is a full Claude Code session with its own complete window, the single most expensive unit of work in the toolkit. Cost scales roughly linearly with the number of active agents, so a 5-teammate team is on the order of 5× a single session.

Because of that linearity, the discipline is non-negotiable: profile on a small slice first. Run the audit on one directory, ask the narrow version of the research question, spin up one teammate before five. Read the real token numbers, then multiply by your intended scale before you commit.

Once many agents are spending in parallel, you need to attribute that spend — which skill, which subagent, which phase. Claude Code gives you four lenses, from live to historical to programmatic.

/usage — the breakdown. Shows cost broken down by skill, subagent, plugin, and MCP server. This is your first stop after a big run: it tells you what spent, not just how much.

/insights — the history and trends. Where /usage is a snapshot, /insights gives you history, per-skill cost, and trends over time — so you can see that a particular skill or workflow has quietly become your biggest line item across many sessions.

/workflows — live per-phase, per-agent tokens. While a workflow runs, drill into a phase (Enter / →) to see agent count, token totals, elapsed time, and per-agent prompts / tool calls / results. This is the panel you watch during your small-slice profiling run.

OpenTelemetry spans — business attribution. For org-scale accounting, Claude Code emits OpenTelemetry spans carrying agent_id and parent_agent_id. That parent/child linkage lets a cost platform (e.g. CloudZero) roll spend up the orchestration tree — attributing a child agent's tokens back to the workflow or team lead that spawned it — so you can answer "which initiative cost what," not just "which process."

Live, this run:      /workflows   → per-phase / per-agent tokens, elapsed time
This session:        /usage       → cost by skill / subagent / plugin / MCP
Across sessions:     /insights    → history, per-skill cost, trends
Org / business unit: OTel spans   → agent_id + parent_agent_id → cost platform

Coordinating agents multiplies permission decisions, so the model is built on one rule: the parent's mode takes precedence, and a child can only RELAX within the constraints it inherits — never escalate beyond them. If the parent is in bypassPermissions or auto, that wins; a child cannot tighten its way past a parent that's locked down, and it cannot grant itself powers the parent didn't have.

Each layer then has its own behavior within that frame:

Workflow subagents are the surprising one: regardless of the parent's permission mode, they always run in acceptEdits so file edits are auto-approved — but they still carry the parent's allowlist, so a shell command, web fetch, or MCP call that isn't on that allowlist can still prompt you mid-run. (That's why a workflow can pause even though it's supposed to run unattended.)

Routines run on the other extreme: no prompts whatsoever. You can't approve things in a scheduled cloud run, so you bound their reach up front instead — by repos, branch-push settings (branches default to a claude/ prefix), environment network access, and connectors.

And cutting across all of it: protected paths are never auto-approved — .claude, .git, .npmrc, .mcp.json (and the like) — except under bypassPermissions. No permission mode short of full bypass will silently let an agent rewrite your .mcp.json or git internals.

Dynamic Workflows is a research preview and needs v2.1.154+ (claude --version). The traps below come straight from how the runtime is built.

The caps are hard: 16 concurrent / 1,000 total. At most 16 agents run at once (bounded by CPU cores) and 1,000 agent calls per run total. The danger is a silent runaway loop: a generation that recurses or fans out unbounded can burn straight through the 1,000-call cap with no error — just a surprising bill and a stalled run. Read the script Claude generated and sanity-check its loops before approving a large run.

Resume is same-session only. Pause/resume works within one Claude Code session (completed agents return cached results; the rest run live). But there's no checkpoint persistence across sessions — exit Claude Code and the workflow restarts fresh next time. Don't rely on closing your laptop and picking up where you left off.

The meta block must be a literal. The mandatory export const meta = {...} must be a literal object — no function calls, no variables, no dynamic construction. Any deviation breaks parsing:

// CORRECT — a literal
export const meta = {
  name: 'audit',
  description: 'Audit a directory for X',
  phases: [{ title: 'Scan' }, { title: 'Verify' }]
};

// BREAKS PARSING — built dynamically
export const meta = buildMeta(process.env.NAME);

No mid-run input. A workflow can't take user input mid-run — only permission prompts can pause it. You can't "answer a question" partway through; design the prompt so the run is self-contained.

Budget overruns — test small. Workflows cost significantly more than single-session work (parallel agents, full context per agent). The mitigation is the same discipline as everywhere else: run it on one directory / a narrow question first, watch per-phase tokens in /workflows, then scale.

API note: different sources name the scripting primitives differently — the official docs describe spawn(definition, prompt, args); third-party writeups describe agent(), parallel(), pipeline(), phase(). Don't memorize an API. Read the script Claude actually generates and lean on /help for your version.

Agent teams are experimental and disabled by default — you must opt in:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# or settings.json: { "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

Because they're experimental, the rough edges are real and worth knowing before you trust a team with real work:

• /resume and /rewind do NOT restore in-process teammates. Session restore brings back your lead, not the live teammates — you'll re-create them. Don't treat a team as durable across a restart.
• Task status lags. Teammates sometimes finish work but fail to mark the task complete. When the shared task list looks stuck, nudge them manually ("mark your task complete") rather than assuming they're still working.
• Shutdown is slow. The lead requests exit and the teammate approves it — this can take a while. Budget time; don't yank the session.
• One team at a time per lead, no nested teams, and no lead transfer (the lead is your main session, fixed).
• Cleanup MUST run from the lead. Say "clean up the team" to the lead session — that removes the shared task list (~/.claude/tasks/{team-name}/), mailbox, and config consistently. Running cleanup from a teammate won't tidy shared resources.

Cost reminder: every teammate is a full context window, so size to 3–5 teammates with ~5–6 tasks each and don't leave teams running unattended — idle teammates are still expensive context windows.

Unattended and cloud features have their own failure surface — these are the ones learners hit first.

Unpinned background sessions stop after ~1 hour. Background sessions live in a per-user supervisor (daemon), and unpinned idle sessions stop after ~1 hour. If you want one alive while you're away, pin it (Ctrl+T in agent view) — pinned sessions also get restarted by the supervisor on a binary update.

Supervisor stalled? Restart it without losing work.

claude daemon status                    # diagnose
claude daemon stop --any --keep-workers # restart supervisor, PRESERVE sessions

The --keep-workers flag is the important part: it restarts the supervisor while preserving the running sessions.

/goal can't read files — it judges from the transcript only. /goal <condition> pursues a condition across turns, but a small fast model (typically Haiku) evaluates after each turn from the transcript ONLY — it can't run shell or read files independently. So the condition must be provable from Claude's own output. "All tests in test/auth pass" only works if Claude actually runs them and the result is in the transcript; a condition that requires inspecting a file the goal-checker can't see will never resolve.

Provider limits — Monitor, PushNotification, and the ultra features. Several capabilities are unavailable on Bedrock / Vertex / Foundry / ZDR: the Monitor and PushNotification tools, plus ultraplan / ultrareview. (Dynamic workflows are available on Bedrock/Vertex/Foundry; /loop, agent teams, and agent view are local.) Two more sharp edges: Monitor is also disabled with DISABLE_TELEMETRY / CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC; and ultraplan disconnects Remote Control (both use claude.ai/code), so you can't run cloud planning and a phone-connected Remote Control session at once.

These features are new and move fast. State this plainly to yourself before you build on them:

• Research preview: Dynamic Workflows (v2.1.154+), agent view / background agents (v2.1.139+), ultraplan / ultrareview, cloud routines.
• Experimental, OFF by default: Agent teams (v2.1.32+) — opt in with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• Current keywords (NOT deprecated): ultracode (triggers dynamic workflows) and ultrathink (deeper reasoning for one prompt) are current.

Because flags, caps, and even the scripting-API surface shift between versions, two habits keep you safe: check claude --version before assuming a feature exists, and defer to /help and the live docs for your installed version rather than to anything memorized — including this lesson. When in doubt about a workflow's behavior, read the script Claude generated; it's the ground truth for that run.