Agent Context Exhaustion and Continuation: Spawning Replacement Agents Mid-Wave

Agent Context Exhaustion and Continuation

Problem

During multi-wave agent team execution, a late-phase agent may exhaust its context window before completing all assigned work. The agent stops mid-implementation — some files are modified, others untouched. The leader detects partial completion but the agent is no longer responsive.

Symptoms:

• Agent reports idle or goes silent after partial work
• git status shows a subset of expected modified/new files
• Earlier layers (domain, application) are done but later layers (infrastructure, framework, frontend) are missing
• The agent’s final message (if any) may not mention incompleteness

Investigation

Detection Pattern

At each wave gate, the leader should verify completeness:

# Compare expected files against actual modifications
git status --short
# Expected: M file1.rs, M file2.rs, ?? new_file.tsx, ?? new_file.ts
# Actual:   M file1.rs only → agent exhausted context

Why It Happens

Late-phase agents accumulate context from:

1. Large initial prompts (~5-10k tokens for detailed wave instructions)
2. Multiple file reads to understand existing patterns (~2-4k per file)
3. File edits with surrounding context
4. Test runs and error fixing loops
5. Quality gate output (clippy, typecheck)

Agents working on 6+ files across 4+ layers in a single wave are most at risk.

Root Cause

Agent context windows are finite. When a wave assigns work spanning multiple architectural layers (application → infrastructure → framework → frontend), the agent may exhaust its context after completing earlier layers, leaving later layers untouched.

The risk increases when:

• Agent prompts include extensive code examples and patterns
• The agent reads many files to understand existing conventions
• Multiple compilation/test cycles consume context on error fixing
• Wave scope crosses more than 3 architectural layers

Solution

Continuation Agent Pattern

When an agent exhausts context mid-wave, spawn a continuation agent with:

1. Explicit completion status — what the previous agent finished
2. Remaining scope only — don’t repeat completed work instructions
3. Same configuration — same model, mode, and file ownership rules
4. Pattern references — point to existing code for the remaining work

## Task: Complete Wave N Remaining Work

The previous agent completed:
1. ✅ CreateBlockUseCase with 5 tests
2. ✅ insert_block() trait method in services.rs
3. ✅ mod.rs re-exports

You need to complete the remaining layers:

### 1. SQLite Implementation
[Specific instructions with pattern reference]

### 2. Tauri Command
[Specific instructions with pattern reference]

### 3. Frontend Components
[Specific instructions]

### IMPORTANT: DO NOT modify files already completed above.

Key Principles

1. Check before spawning: Verify the previous agent’s work compiles (cargo check) before launching the continuation agent. Fix any partial state first.

2. Reference, don’t repeat: Instead of re-explaining codebase patterns in the prompt, point to specific existing files and line numbers: “Follow the update_block_metadata command pattern at commands/page.rs:769.”

3. Same team context: Spawn the continuation agent in the same team so it shares the task list and can be tracked consistently.

4. Leader commits both: Neither the original nor continuation agent should commit. The leader verifies the combined output at the wave gate and commits once.

Example: INK-233 Wave 4

Original agent insert-flow completed:

• crates/application/src/page/create_block.rs (new use case + 5 tests)
• crates/application/src/page/services.rs (trait method added)
• crates/application/src/page/mod.rs (re-exports)

Continuation agent insert-flow-2 completed:

• crates/infrastructure/sqlite/src/workspace/page_repository.rs (insert_block impl)
• apps/desktop/src-tauri/src/commands/page.rs (create_block command)
• apps/desktop/src-tauri/src/commands/attachment.rs (upload_attachment_bytes — bonus)
• apps/desktop/src-tauri/src/main.rs (command registration)
• apps/desktop/src-react/components/editor/InsertBlockMenu.tsx (new component)
• apps/desktop/src-react/components/editor/extensions/ImageBlockDrop.ts (new extension)
• apps/desktop/src-react/components/editor/InklingsEditor.tsx (extension wiring)
• packages/contracts/generated/bindings.ts (regenerated)

Combined output: 12 files, 798 insertions. All quality gates passed on first attempt.

Prevention

Foundation Wave Pre-Inclusion

When planning multi-wave epics, identify methods that downstream agents will need from shared files (typically domain entities). Pre-include these methods in the foundation wave agent’s scope, even if they logically belong to downstream issues.

Example from INK-233:

• Wave 1 (INK-263) pre-included methods specified in Wave 2 issues:
  • searchable_text() from INK-269 (FTS5)
  • to_markdown() from INK-270 (markdown export)
  • validate_caption(), validate_link_url(), validate_scale_percentage() from INK-266
• Cost: ~30 extra lines in Wave 1
• Benefit: Eliminated domain file conflicts for 2 parallel Wave 2 agents

When to pre-include:

• The method is specified in a downstream issue’s acceptance criteria
• Multiple downstream agents would need to modify the same file
• The method’s signature and behavior are clear from the plan

When NOT to pre-include:

• The method’s design depends on infrastructure discoveries during implementation
• The foundation agent’s scope is already large enough to risk context exhaustion

Context Budget Estimation

Before spawning a wave agent, estimate context consumption:

Activity	Approximate Tokens
Detailed agent prompt	3-8k
File read (per file)	1-4k
File edit (per edit)	0.5-2k
Test/compile output	2-5k per run
Quality gate (clippy + typecheck)	3-8k

Rule of thumb: If estimated consumption exceeds 70% of context window, either split into two agents upfront or plan for continuation.

Scope Splitting Guidelines

For agents crossing 4+ layers, consider pre-splitting:

Agent A (Backend)	Agent B (Frontend)
Use case + tests	React components
Repository trait + impl	TipTap extensions
Tauri command + wiring	Editor integration

This is more reliable than spawning a single agent and hoping it fits in context.

Warning Signs

• Agent prompt exceeds 5k tokens (high risk of context exhaustion)
• Scope spans 4+ architectural layers
• Agent needs to read 8+ files to understand patterns
• Wave includes both backend and frontend work for a single agent

References

• Branch: matt/ink-233-introduce-block-content-types (commits e6c2ff6..2e8721e)
• Linear: INK-274, INK-276 (Wave 4 issues completed via continuation)
• docs/solutions/workflow-issues/agent-team-orchestration-at-scale.md — wave planning and file ownership
• docs/solutions/workflow-issues/agent-team-uncommitted-work.md — leader commit patterns