[DOCS] [Workflows] Workflow `agent()` subagents were missing per-agent attribution headers, but `workflows.md` does not document the per-agent attribution layer at all

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/workflows

Section/Topic

The "How a workflow runs" section and the "Manage runs" → "Cost" subsection in docs/en/workflows.md. The v2.1.174 changelog fixes a case where workflow agent() subagents were missing per-agent attribution headers, but the page does not describe what attribution headers are added to subagent requests or what they mean for cost/usage breakdowns.

Current Documentation

docs/en/workflows.md (line 197-213) currently says:

"## How a workflow runs The workflow runtime executes the script in an isolated environment, separate from your conversation. Intermediate results stay in script variables instead of landing in Claude's context. Every run writes its script to a file under your session's directory in ~/.claude/projects/. Claude receives the path when the run starts, so you can ask for it. You can open that file to read the orchestration Claude wrote, diff it against a previous run's script, or edit it and ask Claude to relaunch from the edited version. The runtime tracks each agent's result as the run progresses, which is what makes a run [resumable](#resume-after-a-pause) within the same session. ### Behavior and limits The runtime applies the following constraints: | Constraint | Why | | :------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------- | | No mid-run user input | Only agent permission prompts can pause a run. For sign-off between stages, run each stage as its own workflow | | No direct filesystem or shell access from the workflow itself | Agents read, write, and run commands. The script coordinates the agents | | Up to 16 concurrent agents, fewer on machines with limited CPU cores | Bounds local resource use | | 1,000 agents total per run | Prevents runaway loops |"

docs/en/workflows.md (line 226-230) currently says:

"### Cost A workflow spawns many agents, so a single run can use meaningfully more tokens than working through the same task in conversation. Runs count toward your plan's usage and rate limits like any other session. To gauge the spend before committing to a large task, run the workflow on a small slice first: one directory instead of the whole repo, or a narrow question instead of a broad one. The /workflows view shows each agent's token usage as the run progresses, and you can stop the run there at any time without losing completed work. The runtime's [agent caps](#behavior-and-limits) limit how many agents a single run can spawn, which bounds the cost of a runaway script."

The v2.1.174 changelog entry reads:

"Fixed Workflow tool agent() subagents missing per-agent attribution headers"

What's Wrong or Missing?

A. The page never explains that workflow subagents are request-scoped and need per-agent attribution

The runtime description says "agents read, write, and run commands" but does not say each subagent's outgoing requests carry attribution headers that identify them as subagents of a specific parent workflow run, or that those headers are what the cost-tracking view uses to attribute tokens to an agent.

B. The "Cost" subsection relies on attribution that was broken

The /workflows view shows "each agent's token usage as the run progresses." Before v2.1.174, workflow agent() subagents were missing the per-agent attribution headers, so the per-agent breakdown in /workflows would not separate those subagents from the parent workflow or from each other. The page presents per-agent cost tracking as a normal feature but does not say which attribution path it depends on.

C. The "Behavior and limits" table does not mention attribution as a runtime concern

The constraints table covers concurrency and turn limits but says nothing about what each spawned agent carries. A user reading the page has no way to predict that attribution headers are involved, or that losing them collapses the per-agent cost view.

Suggested Improvement

Option A: Comprehensive fix

1. In docs/en/workflows.md (line 197-203), add a short paragraph under "How a workflow runs" describing the attribution layer:

> "The runtime adds per-agent attribution headers to every request a workflow subagent makes. The headers identify the request as belonging to a specific workflow run and a specific subagent, which is what the per-agent token usage shown in /workflows is grouped by. As of v2.1.174, agent() subagents carry the same per-agent headers as other workflow subagents, so the cost view breaks them out the same way."

1. In the "Behavior and limits" table (line 207-214), add a row that ties attribution to the cost view:

> "| Per-agent attribution headers | Required for the per-agent token breakdown in /workflows and for the run totals on the parent workflow. Each agent() subagent request carries the headers; v2.1.174 fixes a case where they were missing |"

1. Cross-reference the new paragraph from the "Cost" subsection (line 226-230):

> "The per-agent token usage in /workflows is grouped by the per-agent attribution headers that the runtime adds to each subagent request. See [How a workflow runs](#how-a-workflow-runs) for what those headers are and the v2.1.174 fix that makes the breakdown reliable for agent() subagents."

Option B: Minimum fix

Add the attribution paragraph to "How a workflow runs" only. Leave the "Behavior and limits" row and the "Cost" cross-reference for a later pass.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/workflows | 197-203 | "How a workflow runs" — does not describe the per-agent attribution headers that the runtime adds |
| https://code.claude.com/docs/en/workflows | 207-214 | "Behavior and limits" — does not mention attribution as a runtime concern |
| https://code.claude.com/docs/en/workflows | 226-230 | "Cost" — references the per-agent token usage view but does not say which attribution layer it depends on |
| https://code.claude.com/docs/en/agent-sdk/overview | (n/a) | Agent SDK overview also runs subagents; cross-reference is helpful but not strictly required |
| https://code.claude.com/docs/en/changelog | 24 | Sole mention of the v2.1.174 fix; no cross-references |

Total scope: 1 page with three distinct gaps, plus the changelog.

Cross-references:

• https://code.claude.com/docs/en/sub-agents — subagent model overrides are documented there; the workflow attribution paragraph should note that workflow subagents are a separate dispatch path
• https://code.claude.com/docs/en/monitoring-usage — OTEL_LOG_TOOL_DETAILS and the skill.name example at line 478 show per-call attribution in monitoring; the workflow attribution paragraph should cross-reference for users who also monitor usage

Version: v2.1.174 (June 12, 2026)