agent-context-isolation

用途

Agent Context Isolation 是一套规则，用于在多个 AI 子代理协作时，防止代理输出污染主对话的上下文窗口（context window）。其核心目标是把代理的完整转录挡在主上下文之外，只把必要的结果以文件形式传回。

主要能力与规则

1. 使用带文件协调的后台代理

正确的做法是让后台代理把结果写入文件，主上下文读取该文件：

# 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)

以 run_in_background=true 运行的后台代理会隔离其上下文。应让它们把结果写入 .claude/cache/agents/<agent-type>/ 下的文件。

2. 切勿使用 TaskOutput 获取结果

# 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 会返回代理的完整转录，因此应始终改用基于文件的协调方式。

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

系统提醒会自动到达，例如：

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

检测完成的方式：

观察进度提醒是否停止到达
轮询预期的输出文件：find .claude/cache/agents -name "*.md" -mmin -5
检查任务输出文件大小增长：wc -c /tmp/claude/.../tasks/<id>.output

卡住代理的检测信号：

进度提醒停止到达
任务输出文件大小停止增长
在合理时间内未创建预期输出文件

4. 用测试验证，而非用输出验证

代理工作完成后：

直接运行测试套件：bun test
报告通过/失败数量
仅在测试失败时才排查问题

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

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)

每个代理读取上一个代理的文件输出，而不是 TaskOutput。

为何重要

代理上下文隔离可以保留主对话的上下文预算。通过 TaskOutput 读取代理输出会淹没上下文，进而导致：

对话中途压缩
丢失用户原始请求的上下文
需要重复解释

来源说明

资料提到该做法源于一次 TaskOutput 将 70k+ tokens 灌入主上下文的会话；另有 2026-01-01 的会话成功将后台代理与文件协调用于 SDK Phase 3。更具体的实现细节、安装方式与配置项在提供的资料中暂未提供。