What is the purpose of agent-context-isolation?

To prevent the main context from being polluted by agent transcripts by using background agents and file-based outputs, preserving the context budget and readability.

How do I verify results?

Check the output.md files under .claude/cache/agents/ /, and run bun test to verify results; never rely on TaskOutput.

How do I detect a stuck agent?

Look for stalled progress reminders, non-growing output file sizes, or missing expected output files after a reasonable wait; use file checks and tests to confirm.

agent-context-isolation

npx machina-cli add skill parcadei/Continuous-Claude-v3/agent-context-isolation --openclaw

Files (1)

SKILL.md

2.7 KB

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:

Progress reminders stop arriving
Task output file size stops growing
Expected output file not created after reasonable time

4. Verify with Tests, Not Output

After agent work:

Run the test suite directly: bun test
Report pass/fail counts
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

Source

git clone https://github.com/parcadei/Continuous-Claude-v3/blob/main/.claude/skills/agent-context-isolation/SKILL.mdView on GitHub

Overview

Agent Context Isolation prevents agent output from polluting the main context window by using background agents that write results to files instead of TaskOutput. This preserves the main conversation's context budget and enables deterministic, testable results.

How This Skill Works

Use background agents (run_in_background=true) that write results to a file path like .claude/cache/agents/<agent-type>/output.md. The main agent reads these files rather than TaskOutput, and you verify outputs through tests (bun test) and by inspecting the output files.

When to Use It

When you must prevent TaskOutput from flooding the main context and polluting the context budget.
In a multi-step agent pipeline (research → plan → validate → implement) where each agent reads the previous output file.
When outputs need to be verifiable and auditable, stored as files rather than transient transcripts.
During debugging or monitoring to detect progress and completion via system reminders and file existence.
When you want automated verification by running tests instead of relying on in-context transcripts.

Quick Start

Step 1: Run subagents in background: Task(subagent_type="...", run_in_background=true) to write to .claude/cache/agents/<agent-type>/output.md
Step 2: Do not use TaskOutput; read the output file and verify with tests (bun test)
Step 3: Monitor progress via system reminders and confirm completion when the output file appears and tests pass

Best Practices

Run subagents in the background (run_in_background=true) to isolate their context.
Write results to .claude/cache/agents/<agent-type>/output.md and never use TaskOutput.
Adopt the file-based coordination pattern where each agent reads the previous agent's output file.
Monitor progress via system reminders and check for expected output files to gauge completion.
After work completes, validate with tests (bun test) before integrating results.

Example Use Cases

Right pattern: background agent writes to .claude/cache/agents/<agent-type>/output.md; main reads that file.
Wrong pattern: foreground agent dumps the full transcript into the main context via TaskOutput.
Verification example: Bash("ls -la .claude/cache/agents/<agent-type>/") to confirm outputs exist.
Test-based validation: run bun test to confirm the agent's results meet expectations.
Pipeline demonstration: Research → Plan → Validate → Implement, each step reading the previous output file from the designated cache path.

Frequently Asked Questions

Add this skill to your agents