---
name: Agent Context Isolation
slug: agent-context-isolation-2
category: AI Engineering
description: Agent Context Isolation keeps background agent work out of the main context by writing results to files. Use it when coordinating multiple agents, monitoring progress, or verifying work without pulling full transcripts into chat.
github: "https://github.com/vibeeval/vibecosystem/tree/main/skills/agent-context-isolation"
language: "C#"
stars: 528
forks: 44
install: "npx degit https://github.com/vibeeval/vibecosystem/tree/main/skills/agent-context-isolation ~/.claude/skills/agent-context-isolation"
installs_to: ~/.claude/skills/agent-context-isolation
source_path: skills/agent-context-isolation/SKILL.md
collection_size: 25
category_size: 2451
collection_url: "https://dirskills.com/collections/vibeeval/vibecosystem"
added: 2026-08-26T05:11:55.351Z
last_synced: 2026-08-26T05:11:55.351Z
canonical_url: "https://dirskills.com/skills/agent-context-isolation-2"
---

# Agent Context Isolation

Agent Context Isolation keeps background agent work out of the main context by writing results to files. Use it when coordinating multiple agents, monitoring progress, or verifying work without pulling full transcripts into chat.

**Install:**

```bash
npx degit https://github.com/vibeeval/vibecosystem/tree/main/skills/agent-context-isolation ~/.claude/skills/agent-context-isolation
```

## README

# 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 output file size stops growing
3. Expected output file not created after reasonable time

### 4. Verify with Tests, Not Output
After agent work:
1. Run the test suite directly: `bun test`
2. Report pass/fail counts
3. Only investigate failures if tests fail

### 5. File-Based Agent Pipeline Pattern
```
Research agent → .claude/cache/agents/oracle/output.md
                          ↓
Plan agent → .claude/cache/agents/plan-agent/output.md (reads research)
                          ↓
Validate agent → .claude/cache/agents/validate-agent/output.md (reads plan)
                          ↓
Implement agent → src/module.ts (reads validated plan)
```

Each agent reads the previous agent's file output, not TaskOutput.

## Why This Matters

Agent context isolation preserves the main conversation's context budget. Reading agent outputs via TaskOutput floods context, causing:
- Mid-conversation compaction
- Lost context about user's original request
- Repeated explanations needed

## Source
- Session where TaskOutput flooded 70k+ tokens into main context
- Session 2026-01-01: Successfully used background agents with file-based coordination for SDK Phase 3