Back to Details

agent-context-isolation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Context Isolation

Agent上下文隔离

Prevent agent output from polluting the main context window.
防止Agent输出污染主上下文窗口。

Rules

规则

1. Use Background Agents with File-Based Coordination

1. 使用基于文件协调的后台Agent

undefined
undefined

RIGHT - background agent writes to file, main reads file

RIGHT - background agent writes to file, main reads file

Task(subagent_type="...", run_in_background=true, prompt="... Output to: /path/to/file.md")
Task(subagent_type="...", run_in_background=true, prompt="... Output to: /path/to/file.md")

WRONG - foreground agent dumps full transcript into main context

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>/`.
Task(subagent_type="...", run_in_background=false)

设置`run_in_background=true`的后台Agent会隔离其上下文。让它们将结果写入`.claude/cache/agents/<agent-type>/`目录下的文件中。

2. Never Use TaskOutput to Retrieve Results

2. 切勿使用TaskOutput获取结果

undefined
undefined

WRONG - dumps entire transcript (70k+ tokens) into context

WRONG - dumps entire transcript (70k+ tokens) into context

TaskOutput(task_id="<id>") TaskOutput(task_id="<id>", block=true)
TaskOutput(task_id="<id>") TaskOutput(task_id="<id>", block=true)

RIGHT - check expected output files

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.
Bash("ls -la .claude/cache/agents/<agent-type>/") Bash("bun test") # verify with tests

TaskOutput会返回完整的Agent交互记录。请始终使用基于文件的协调方式替代。

3. Monitor Agent Progress via System Reminders

3. 通过系统提醒监控Agent进度

undefined
undefined

System reminders come automatically:

System reminders come automatically:

"Agent a42a16e progress: 6 new tools used, 88914 new tokens"

"Agent a42a16e progress: 6 new tools used, 88914 new tokens"

To detect completion:

To detect completion:

- Watch for progress reminders to stop arriving

- Watch for progress reminders to stop arriving

- Poll for expected output files: find .claude/cache/agents -name "*.md" -mmin -5

- 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

- 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

**Agent卡顿检测：**
1. 进度提醒停止出现
2. 任务输出文件大小停止增长
3. 在合理时间内未生成预期的输出文件

4. Verify with Tests, Not Output

4. 通过测试而非输出结果进行验证

After agent work:
  1. Run the test suite directly: 
    bun test
  2. Report pass/fail counts
  3. Only investigate failures if tests fail
Agent完成工作后：
  1. 直接运行测试套件：
    bun test
  2. 报告测试通过/失败的数量
  3. 仅在测试失败时再排查问题

5. File-Based Agent Pipeline Pattern

5. 基于文件的Agent流水线模式

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.
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)
每个Agent读取前一个Agent的文件输出，而非使用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
Agent上下文隔离能节省主对话的上下文预算。通过TaskOutput读取Agent输出会充斥上下文，导致：
  • 对话中途出现上下文压缩
  • 丢失与用户原始请求相关的上下文
  • 需要重复解释内容

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
  • 某次因TaskOutput向主上下文注入70k+ tokens的会话
  • 2026-01-01会话：成功使用基于文件协调的后台Agent完成SDK第三阶段开发