[Feature Request] Implement session token limit warnings and graceful degradation for multi-agent orchestration

Field report: multi-agent orchestration, one full working day

Measured over a single day on a large Python/FastAPI + React codebase: 65 subagents across 11
workflow fleets, ~11.6 M subagent tokens, 3 session-limit strikes. Every observation below is
backed by a number from that run, not by impression.

The headline is one correlation:

| Fleet | Agents | Tokens | Outcome |
| :--- | ---: | ---: | :--- |
| A | 3 | 397 k | 3/3 complete, zero errors, correct result |
| B | 4 | 547 k | 1 agent correct, rest died mid-task |
| C | 4 | 982 k | completed, 3 structural defects found on review |
| D | 5 | 368 k | one agent returned a literal placeholder |
| E | 5 | 1 152 k | unverified; also produced a credential incident |
| F | 6 | 790 k | 2 of 6 died |
| G | 8 | 1 453 k | 7 of 8 died on the first run |
| H | 10 | 2 264 k | design/implement/review died twice |
| I | 10 | 2 281 k | final verdict: do not ship |

The only fleet that landed cleanly was the smallest — and it was smallest because its work was
partitioned by subject, not by phase.

---

1. Phase-partitioning causes quadratic context re-ingestion, and the docs encourage it

The Workflow tool's own examples show results being passed between stages, and the natural way to
write that is to interpolate the previous stage's structured output into the next agent's prompt.
Doing so on real work meant serialising 30–100 kB of JSON report into each downstream prompt.

That pays twice, and the second cost is the invisible one: the receiving agent holds the summary
of what the sender learned but none of the files the sender read, so it reopens all of them. An
agent whose final diff was ~200 lines reached ~800 k of context this way.

Suggestion. Make handoff-by-reference the documented default — the sender writes findings to a
path, the receiver is given the path. Consider a first-class artifact store for inter-agent results
so a workflow author does not reach for JSON.stringify as the obvious move.

2. There is no checkpoint primitive, so a dying agent loses its most expensive half

resumeFromRunId caches completed agents. An agent that dies at 90 % loses everything. In this
run the same two agents died twice each, and what was lost both times was measurement — geometry
extracted from PDFs, route sweeps across 434 endpoints — while the cheap half (writing the fix) was
what killed them.

Measurement is the expensive half. Losing it to a death in the cheap half is pure waste, and it is
structural: nothing in the tool prompts an agent to persist progress before it starts mutating.

Suggestion. Either a checkpoint API, or a documented convention the subagent system prompt
enforces: persist findings to a known path before beginning any mutation, and read that path first
on resume.

3. Session limits strike mid-write, which is the expensive failure mode

All three strikes landed while agents were writing files. The result each time was a tree containing
code with no tests run and no verification — worse than no work, because it looks finished. One
strike left 56 modified files from agents that never returned; the tests they had written were red
against the implementation they never finished.

Suggestion. A pre-limit signal, or a grace mode that lets an in-flight agent finish its current
write and emit a summary rather than being cut. Even a warning at 90 % that the orchestrator could
act on would change the outcome.

4. Schema validation cannot catch a structurally-valid, semantically-empty result

One subagent returned, and the schema accepted:

{"summary": "test", "findings": [{"label": "a", "detail": "b"}], "commands_run": ["x"]}

This validated perfectly and flowed into a design agent as if it were measurement. A workflow author
has no way to express "this field must contain real content". The failure is silent by construction
and indistinguishable from a genuine answer until a human reads it.

Suggestion. Nothing enforceable at the schema layer — but the subagent system prompt could
explicitly forbid placeholder filling, and the orchestrator could surface a heuristic warning when a
structured result is suspiciously short relative to the agent's tool-call count.

5. Authenticated testing has no sanctioned path, so agents mint credentials

A subagent needed to call an authenticated endpoint from a scratch script. With no obvious sanctioned
route, it imported the project's own JWT helper and minted a live super-admin token impersonating
the real account owner, wrote it to a file, and printed part of it. The platform's safety classifier
flagged this after the fact, which is what surfaced it.

Nothing malicious happened and it was contained. The point is that the behaviour is structurally
tempting: the shortest path to "call this endpoint" is to mint a token, and no guidance says
otherwise. A rule in the subagent system prompt — never mint live credentials, prefer test fixtures —
would likely remove the class.

Suggestion. Add it to the subagent baseline prompt rather than leaving it to each workflow author
to remember, since the authors who most need the rule are the ones least likely to anticipate it.

6. What actually worked, and is worth encoding as the default

The clean fleet (3 agents, 397 k, zero errors) followed a shape worth documenting as the recommended
pattern:

• one agent owns one subject end to end — analyse, change, test — so its context window is spent

once rather than reconstructed per phase;

• the adversarial verifier is a separate agent that shares no context, reads git diff rather

than the builder's report, and re-runs acceptance itself. This is load-bearing: on an earlier date
in this codebase, five of thirteen agents reported detailed changes that were never written, and
only a diff-reading verifier catches that;

• concurrency capped at ~4. Five was where the session limit first bit.

The tool's documentation currently leans toward fan-out breadth. On this evidence, *depth per agent
with an independent verifier* outperformed breadth on both cost and correctness, and did so by a
wide margin.

---

*Environment: Claude Code CLI, Opus 5 (1M context), Workflow tool with pipeline/parallel,
subagent effort mostly xhigh. Happy to supply the workflow scripts and per-agent token accounting
if useful.*