[BUG] Ultracode removes proportionality: "use the Workflow tool on every substantive task; token cost is not a constraint" turns a settings audit into 325 agents and a design task into 16, re-reading what the main loop already read, on a sticky effort setting the user cannot see

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code (2.1.260 bundled in Claude Desktop 1.46388.4; 2.1.258 standalone)

What's Wrong?

Ultracode removes the model's judgement about whether a task needs agents at all, and then multiplies the agents it spawns. The result is agent counts and token spend that have no relationship to the size of the task. The numbers below are from one machine, so they are few; the shape is the point, not the sample size.

When a session's effort level is Ultracode, every turn carries this standing instruction:

Ultracode is on: optimize for the most exhaustive, correct answer — not the fastest or cheapest. Use the Workflow tool on every substantive task; token cost is not a constraint. See the Ultracode section and quality patterns in the workflow authoring reference. Solo only on conversational/trivial turns.

plus the workflow-authoring skill, whose "quality patterns" are multiplicative by construction: adversarial verify ("spawn N independent skeptics per finding"), judge panels, loop-until-dry ("keep spawning finders until K consecutive rounds return nothing new"), completeness critic ("what it finds becomes the next round of work"). The Workflow tool's own description says "keep workflows under 15 agents. This is a guideline, not a hard limit." Under the instruction above, the guideline loses every time.

Four things follow, each measured here:

1. The task no longer decides the fan-out; the mode does. A settings-consistency audit of a desktop app's UI became 325 agents: six "finder" lenses, then one adversarial-verify agent per batch of their findings (319 of them), then a synthesizer. A design-and-build task in the reporting session became 16 agents (ten web researchers, five codebase readers, one critic) for one prompt. Eight of the thirteen Workflow runs on this machine exceeded the tool's own 15-agent guideline. The week before, the same user did the same kinds of work (settings audits, PR reviews, UI rebuilds) in this repository with zero Workflow agents and shipped it.

2. The agents redo work the main loop already did. In the reporting session the main loop had made 38 tool calls (36 of them file reads and greps) and spent 163K output tokens scouting the codebase before it spawned five "codebase reader" agents to read the same files again, because subagents do not share the main context. Every agent re-reads from scratch. Across four days Workflow agents consumed 1.37B input tokens (uncached + cache writes + cache reads) against 2.69M output tokens; the input is almost entirely context being re-read per agent.

3. The person paying cannot see the mode, did not choose it this week, and cannot scale it. Ultracode is stored per session in the desktop app (sessionSettings.ultracode: true) and carries over into new sessions. On this machine 133 of 174 desktop sessions since Aug 15 carry it. No prompt since Aug 26 contains the word ultracode (checked across every transcript; the only earlier mentions, on Aug 23, are about a settings page in the user's own product). The stored effort field reads xhigh, so the effort control does not say "ultracode" either. Reasoning depth (xhigh) and orchestration breadth (hundreds of agents) are one dial: a person choosing "think harder" has also chosen "spawn as many agents as the patterns produce".

4. The spend has no relationship to the account's limit. On a subscription plan the cost is the session limit. The instruction says cost is not a constraint; the tool never checks remaining usage, never caps concurrency against it, and does not stop when the first agent is refused. So the predictable end of a 325-agent run was 318 agents refused with You've hit your session limit, an empty result, and a blocked main session until the reset. That is the consequence, not the defect; the defect is that 325 agents were spawned for that task.

Measured (local transcripts, ~/.claude/projects/**, message.usage summed per assistant message)

| window | sessions | Ultracode on | Workflow agents | subagent share of output tokens |
|---|---|---|---|---|
| Aug 26 – Sep 1 | 85 | 77 | 0 | 1% |
| Sep 2 – Sep 5 | 7 | 7 | 499 | 27% |

Every Workflow run on this machine:

| started (PT) | Claude Code | model | agents | over the 15-agent guideline | returned nothing | refused on the session limit |
|---|---|---|---|---|---|---|
| Sep 01 19:26 | 2.1.247 | claude-opus-5 | 20 | yes | 0 | 0 |
| Sep 01 19:29 | 2.1.255 | claude-opus-5 | 16 | yes | 0 | 0 |
| Sep 01 20:15 | 2.1.255 | claude-opus-5 | 8 | | 0 | 0 |
| Sep 01 22:27 | 2.1.247 | claude-opus-5 | 14 | | 0 | 0 |
| Sep 01 22:43 | 2.1.247 | claude-opus-5 | 16 | yes | 0 | 0 |
| Sep 01 22:56 | 2.1.247 | claude-opus-5 | 6 | | 0 | 0 |
| Sep 01 23:52 | 2.1.247 | claude-opus-5 | 13 | | 0 | 0 |
| Sep 03 19:02 | 2.1.258 | claude-fable-5-1 | 4 | | 0 | 0 |
| Sep 03 19:23 | 2.1.258 | claude-fable-5-1 | 325 | yes | 319 | 318 |
| Sep 03 19:32 | 2.1.258 | claude-fable-5-1 | 6 | | 1 | 1 |
| Sep 03 19:55 | 2.1.258 | claude-fable-5-1 | 16 | yes | 16 | 16 |
| Sep 04 17:37 | 2.1.258 | claude-fable-5-1 | 25 | yes | 12 | 0 |
| Sep 05 01:44 | 2.1.260 | claude-opus-5 | 30 | yes | 16 | 0 |

Tokens consumed by those 499 agents in four days:

| | output tokens | input tokens (uncached + cache writes + cache reads) |
|---|---|---|
| agents that returned a result (135) | 2,492,734 | 1,168,788,007 |
| agents that returned nothing (364) | 198,856 | 199,690,506 |
| all Workflow agents | 2,691,590 | 1,368,478,513 |

That is roughly 30% of everything those seven sessions spent, on top of a main loop that was already running at xhigh.

What Should Happen?

• A fan-out is a decision about a task, not a session mode. Remove the standing "use the Workflow tool on every substantive task" instruction and the "token cost is not a constraint" sentence. If a mode that biases toward orchestration is wanted, it should ask the model to size the fan-out to the task and to say what it will cost before spawning.
• Separate reasoning depth from orchestration breadth. "xhigh" should mean xhigh. Orchestration should be its own explicit, per-task choice (the ultracode keyword already exists for that), not a side effect of the effort dial.
• Make the mode visible and non-sticky. A badge while it is active, the effort control reading "ultracode" rather than "xhigh", and no carry-over into new sessions.
• Cap by default and confirm above the cap. A hard default ceiling per Workflow call (the existing 15 is fine) that the mode cannot override, and a confirmation showing the agent count for anything above it.
• Do not send agents to redo the main loop's reading. Subagents that would re-read files the main context already holds should receive that context or not be spawned.
• Respect the account's limit: pre-flight against remaining usage, stop the run on the first session limit refusal, and return partial results instead of []/null.

Error Messages/Logs

Workflow completion notification, Sep 3 (the 16-agent run):

[research:hermes] failed: You've hit your session limit · resets 11:40pm (America/Los_Angeles)
[research:cline] failed: You've hit your session limit · resets 11:40pm (America/Los_Angeles)
... (14 more identical lines)
<usage><agent_count>16</agent_count><agents_done>0</agents_done><agents_error>16</agents_error><subagent_tokens>1255381</subagent_tokens><tool_uses>430</tool_uses><duration_ms>775936</duration_ms></usage>
result: {"profiles":[],"readings":[],"critic":null}

The 325-agent script's own phases, from its persisted meta: Find ("six independent lenses over code + screenshots") → Dedup → Verify (adversarial, one agent per batch of findings) → Synthesize. Its journal: 325 started, 6 result.

Desktop session record for the reporting session: {"model":"claude-fable-5-1","effort":"xhigh","sessionSettings":{"ultracode":true},"permissionMode":"auto"}

Steps to Reproduce

1. In Claude Desktop (Code tab), set a session's effort level to Ultracode once; start later sessions without touching it. Note that they carry sessionSettings.ultracode: true and receive the instruction quoted above every turn.
2. Give an ordinary engineering prompt: "audit these settings pages for consistency" or "design and build X, here are the requirements".
3. Observe a Workflow fan-out sized by the skill's patterns rather than by the task: finders × verifiers-per-finding, or N researchers + N readers + a critic, typically above the tool's 15-agent guideline.
4. Compare with the same prompt at plain xhigh: the work completes in the main loop with no agents, at a fraction of the tokens.

Method for the numbers: sum message.usage over every type: "assistant" line in ~/.claude/projects/**/<session>.jsonl (main loop) and <session>/subagents/**/*.jsonl (agents); pair started/result entries in each workflow's journal.jsonl; take the Ultracode state and effort from ~/Library/Application Support/Claude/claude-code-sessions/**/*.json. Scripts available on request.

Claude Model

claude-fable-5-1 (also claude-opus-5)

Is this a regression?

Yes

Last Working Version

Behavioural, not tied to a release: the first Workflow fan-out on this machine was on Sep 1 at 19:26 PT under 2.1.247, a build that had run 38 Ultracode sessions since Aug 29 with none. The client's cached remote configuration in ~/.claude.json carries "tengu_workflows_enabled": true, which suggests a server-side rollout. The workflow-authoring skill is present in the 2.1.258 and 2.1.260 binaries and absent from 2.1.233 and 2.1.240 (2.1.247 and 2.1.255 are no longer on disk to check).

Claude Code Version

2.1.258 standalone; 2.1.260 bundled in Claude Desktop 1.46388.4

Platform

Claude Desktop app (Code tab)

Operating System

macOS 26.5.2 (Darwin 25.5.0), Apple Silicon

Terminal/Shell

Claude Desktop Code tab (zsh as login shell)

Additional Information

Written with Claude Code from the session that spawned the 16-agent run, after the user asked why a task that needed no agents had used so many. Every number comes from files on the reporting machine.