name: agent-context-isolation description: Agent Context Isolation user-invocable: false
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"
# To detect completion:
# - Watch for progress reminders to stop arriving
# - Poll for expected output files: find .claude/cache/agents -name "*.md" -mmin -5
# - Check task output file size growth: wc -c /tmp/claude/.../tasks/<id>.output
Stuck agent detection: