blue/.blue/docs/spikes/2026-01-26T1843Z-read-tool-token-limit-on-assembled-dialogue-documents.wip.md

Spike: Read tool token limit on assembled dialogue documents

Status	In Progress
Date	2026-01-26
Time Box	30 minutes

---

Question

Why does the alignment dialogue fail with token limit errors when using file-based subagent output?

---

Root Cause

The error occurs when the Judge agent tries to read the assembled dialogue document after completing all rounds. Individual agent output files are small (~2-3KB each, ~400 words), but the combined dialogue document accumulates:

• 3-6 expert perspectives per round
• Multiple rounds (typically 2-3)
• Each perspective ~400 words
• Plus judge synthesis, tension markers, and metadata

Result: A 4-round dialogue with 5 experts produces ~10KB per round × 4 = ~40KB+, exceeding the Read tool's 25,000 token limit.

Evidence

Error observed:

Read(~/.claude/projects/-Users-ericg-letemcook-fungal-image-analysis/acd9a1b2-29fd-437c-a1
Error: File content (31767 tokens) exceeds maximum allowed tokens (25000)

The path ~/.claude/projects/... is where Claude stores Task output, suggesting the Judge was reading back its own assembled document (not the individual /tmp/blue-dialogue/{slug}/round-N/{agent}.md files).

Already Documented

RFC 0029 (file-based-subagent-output) captured this as Churro T02 (open question at line 159):

When agent output exceeds Write tool buffer limits, should the Task system JSONL approach serve as fallback?

The original dialogue noted:

TENSION T02: Stream vs document modes — when agent output exceeds buffer

What Works

• Individual agent files in /tmp/blue-dialogue/{slug}/round-N/{agent}.md (~2-3KB each)
• Write tool successfully stores agent perspectives
• Round-scoped paths prevent collisions
• Fallback to blue_extract_dialogue(task_id=...) exists for missing files

What Breaks

1. Assembled dialogue documents can exceed Read tool's 25K token limit
2. Judge can't verify its own writes to large dialogue files
3. No paginated read strategy in the judge protocol

Options

A. Paginated reading

Judge reads dialogue with offset/limit parameters. Requires tracking document structure to know what to skip.

B. Streaming writes, chunk reads

Each round writes to a separate section file. Judge assembles by reading chunks. More complexity.

C. Trust-but-verify pattern

Judge writes without reading back the full document. Only reads individual agent files which stay small. Final document assembly happens at dialogue completion, not during.

D. Summary-based continuation

After each round, Judge writes a summary of accumulated state rather than re-reading the full document. Avoids needing to read large files.

Recommendation

Option C (trust-but-verify) aligns with the file-based approach:

1. Judge reads individual agent output files (always small)
2. Judge appends to dialogue document without re-reading it
3. blue_dialogue_save handles final assembly and validation
4. Remove any Judge instructions that require reading the full assembled document mid-dialogue

This requires updating build_judge_protocol in dialogue.rs to not instruct the Judge to read back its own document.

---

Alignment Dialogue Outcome

A 3-expert alignment dialogue reached 100% convergence on an improved architecture:

Dialogue: .blue/docs/dialogues/2026-01-26T1850Z-round-scoped-file-architecture-for-alignment-dialogues.dialogue.recorded.md

Final Architecture

/tmp/blue-dialogue/{slug}/
├─ round-0/
│  ├─ muffin.md          ← Agents write (working artifacts)
│  ├─ cupcake.md
│  └─ scone.md
├─ round-0.dialogue.md   ← Judge assembles (continuity artifact)
├─ round-1/
│  └─ {agent}.md
├─ round-1.dialogue.md
└─ .archive/             ← Post-round archive (optional)

Key Resolutions

Tension	Resolution
Stateless vs stateful synthesis	Stateful by reference — global tension IDs (T01, T02...) enable cross-round references without copying content
What content in synthesis	Full round content — synthesis + all expert perspectives + metadata (~8-12KB per round, safely under 25K)
Cross-round tension references	Global namespace — T01, T02, T03... never reused across rounds
Dual-write burden on Judge	Necessary separation of concerns — prompt templating (pre-round) and synthesis assembly (post-round) serve different consumers

Implementation Changes Required

1. Judge reads per round: ~15-20KB max

   • Current round agent files (~2-3KB × agents)
   • Prior round's round-N.dialogue.md only (~8-12KB) — NOT full history

2. Judge writes per round:

   • Agent prompt files (pre-round, templated)
   • Round dialogue file (post-round, synthesis + perspectives)

3. Agents read per round:

   • All prior round-N.dialogue.md files for context
   • Source grounding files specified in prompt

This eliminates the token overflow by ensuring no single Read exceeds 25K tokens.