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" # 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:** 1. Progress reminders stop arriving 2. Task o...