Agent Context Isolation

Agent Context Isolation

Prevent agent output from polluting the main context window.

Rules

1. Use Background Agents with File-Based Coordination

# RIGHT - background agent writes to file, main reads file
Task(subagent_type="...", run_in_background=true, prompt="... Output to: /path/to/file.md")

# WRONG - foreground agent dumps full transcript into main context
Task(subagent_type="...", run_in_background=false)

Background agents with run_in_background=true isolate their context. Have them write results to files in .claude/cache/agents/<agent-type>/.

2. Never Use TaskOutput to Retrieve Results

# WRONG - dumps entire transcript (70k+ tokens) into context
TaskOutput(task_id="<id>")
TaskOutput(task_id="<id>", block=true)

# RIGHT - check expected output files
Bash("ls -la .claude/cache/agents/<agent-type>/")
Bash("bun test")  # verify with tests

TaskOutput returns the full agent transcript. Always use file-based coordination instead.

3. Monitor Agent Progress via System Reminders

# System reminders come automatically:
# "Agent a42a16e progress: 6 new tools used, 88914 new tokens"