Taming Subagent Bloat in Claude Code 2.1.296

Lachlan Reed

Picture a test runner subagent forty turns deep, still hauling every stack trace it has ever seen into each new request. That's the mess Claude Code 2.1.296 goes after, released October 9th. This episode's brought to you by Jellypod AI. I'm Lachlan, and with me is James.

James Turner

Last time we covered 2.1.292 and the effort parameter for subagents, which lets you dial down reasoning on mechanical jobs like grepping logs. That handled how hard a subagent thinks. 2.1.296 handles how much it carries. The release adds `autoCompactWindow` to subagent frontmatter and to the agents flag definitions. The changelog describes it as letting a subagent auto compact earlier than the main conversation's window.

Lachlan Reed

Here's why that matters. Worker subagents tend to do noisy, repetitive work: running test suites, linters, parsing build logs. All that terminal chatter piles up in context. And every new turn re-sends that whole pile, which shows up as cache reads in your usage, so cost per turn grows with how full the window is. There's also the accuracy side. Long agent sessions on a big window can rot before compaction kicks in, and one GitHub feature request put it as sessions rotting before they reach the roughly 95 percent default. Treat that as a user's description, not an Anthropic benchmark. But the logic is sound: a lean worker beats a bloated one.

James Turner

So the setup is decoupling. Your orchestrator can sit on a huge window with the full architectural history, while workers compact way sooner. Here's the config. In your agent file under the dot claude agents folder, say test-runner.md, the frontmatter has the name test-runner, a description like runs the test suite and inspects stack traces, the model set to Haiku 5.5, effort low, and then `autoCompactWindow` set to 50000. That's the new line. Effort low is the 2.1.292 feature, so the two stack nicely.

Lachlan Reed

And if you're spinning agents up on the fly, same key works in the JSON you pass to the agents flag. Something like claude, the agents flag, then a JSON object with a key called linter, containing the Haiku 5.5 model ID and `autoCompactWindow` of 60000. Worth knowing: the value is an absolute token count, an integer. Not a percentage. Writing 0.5 or fifty percent is not what it wants.

James Turner

Now the caveats, and the first one's a judgment call, so take it as guidance. Compaction costs an LLM call, and the harness reserves up to 20,000 tokens for the summary output. That figure comes from a third party analysis of Claude Code's internals, so treat it as background rather than official docs. The upshot is that if you set the window too low, say under roughly 40,000, a subagent could spend more turns summarizing than working. Starting between 40,000 and 80,000 is a sensible range.

Lachlan Reed

Second caveat: compaction summarizes older turns, so exact details can get condensed. If your subagent needs a specific git hash, a line number, or a raw diff from way back, tell it in its prompt to write those into a scratchpad file. Files survive compaction. Summaries are lossy by nature.

James Turner

One more related addition. `CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL` runs every workflow agent on one model, while other subagents keep theirs. So in CI you can export it as Haiku 5.5 and keep your scripted workflow agents cheap, without touching the specialized reasoning agents. And a quiet one that pairs well: the debug flag now names unrecognized frontmatter fields in custom agent files, with a hint for likely typos. So if you misspell `autoCompactWindow`, you'll find out instead of wondering why nothing compacts.

Lachlan Reed

A few smaller wins. The Read tool gets an `allow_large` option, so Claude can read a text file past the usual size limits in one call, when it needs the whole file and the context has room. Sonnet 5.5 cache reads are now priced at ten cents per million tokens, down from twenty, across the cost command, the status line, the max budget flag, and the SDK's figures.

James Turner

The default limit on MCP tool descriptions and server instructions sent up front doubled, from 2,048 to 4,096 characters. `CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS` lets you set a longer maximum delay when retrying overloaded 529 errors. And debug output for command hooks now logs the command, plugin, outcome, and duration when they finish, so a slow hook finally has a name attached.

Lachlan Reed

Last one: in auto mode, a tool call skipped because the safety check had no usable answer now shows as a dim Not run row, not a red error. Less panic over nothing. So here's your homework. Pick your noisiest subagent, add `autoCompactWindow` at 50000, run it, and watch the context command to see it compact.