Why Your Coding Agent Gets Stuck on Multi-File Tasks: The Sandbox Architecture Problem

You start a coding agent to refactor three files at once.

The agent reads file A correctly, understands the changes needed. Then it opens file B, reads it, gets confused about the context from file A. By the time it tries to edit file C, the agent has forgotten half of what it learned and ends up with broken imports or circular dependencies.

Sound familiar? This isn't a model problem. It's a sandbox problem.

The Hidden Cost of Monolithic Sandboxes

Most coding agents run as a single process inside one sandbox:

Single-Process Agent
├─ Claude / Cursor / OpenCode runtime
├─ Working directory: /tmp/repo
├─ Shell: /bin/bash
├─ Memory: whatever the LLM holds in context
└─ All reasoning + all file operations in one container

The problem emerges fast:

Context window fills up — Agent reads 4 files, reasoning about each edit, token count climbs. By file 3 of a 5-file refactor, the agent is cutting corners on reasoning to stay under the context limit.
Shell state pollution — Agent runs npm install, then git checkout, then npm test. Each command changes the working directory or environment. The agent has to track all of this mentally. One forgotten cd breaks the next five commands.
Sandbox overhead compounds — Booting a sandbox takes 3-5 seconds. For a coding agent that handles one task per session, fine. For an agent that fields quick questions ("fix this one import error") and also handles big refactors, every session is expensive.
Cost per interaction scales — Each question = one full sandbox boot + one full context reconstruction. If your agent takes 100 questions a day to build something, that's $10-20 in wasted sandbox overhead.

The Latency Trap Nobody Talks About

Here's where it gets expensive: teams notice the single-agent pattern is slow, so they try to optimize by running the agent inside the sandbox permanently—reasoning, planning, tool calls, everything in the sandbox.

That works for one agent. At scale (10 agents, 100+ concurrent sessions), your infrastructure looks like:

Per-Agent Sandbox (10 instances)
├─ Agent 1: Full pod with brain + shell (512MB each)
├─ Agent 2: Full pod with brain + shell (512MB each)
├─ ...
└─ Agent 10: Full pod with brain + shell (512MB each)
Total: 5GB baseline, before any actual work

Per-Session Overhead
├─ Sandbox boot: 3-5 seconds
├─ Context reconstruction: 500-1000ms
└─ First meaningful tool call: 5-8 seconds end-to-end

You're paying sandbox time for thinking. That's expensive.

The Brain/Sandbox Separation Pattern

LiteLLM's internal agent (the one that ships 30% of their engineering workload weekly) solved this by splitting the agent into two:

Control Plane (Persistent Brain)
├─ Claude model
├─ Reasoning + planning
├─ Session state (durable)
├─ Tool call decision logic
└─ Runs in shared, persistent pod (no boot overhead)

Data Plane (Ephemeral Sandbox)
├─ Shell + filesystem
├─ Repository
├─ `git`, `npm`, `pytest`
└─ Spins up only when needed, dies after tool call completes

How it works in practice:

Agent reads files, reasons — Brain pod (persistent, 50MB) loads the session, reads your repo metadata, understands what changes to make. Takes ~200ms.
Agent decides first tool call — "I need to edit three files. First, let me read the import structure from utils.ts" — Brain generates the exact command to run.
Ephemeral sandbox boots — Lightweight container with shell + repo clone starts. Takes 1-2 seconds instead of 5+ because it's not running the reasoning model.
Tool executes — grep for imports, cat the file, returns result to brain. Sandbox shuts down immediately.
Brain processes output — Agent decides the next move without re-reading the entire repo. Tool call 2 is faster because context is warm.

Result: Same agent logic, 60% less code, 10x faster multi-file workflows.

Why This Matters for Your Agents

The separation fixes four production problems:

1. Context efficiency — Brain can hold session state across dozens of tool calls without losing context. File A's lessons apply to file B.

2. Cost scaling — One shared brain pod (50MB) + ephemeral sandboxes (1-2 seconds, die fast) beats 10 permanent agent pods (512MB each, always burning cycles).

3. Harness swappability — Brain runs on LiteLLM, sandbox can be any runtime (E2B, Daytona, custom Docker). Change sandboxes without rewriting agent logic.

4. Fast debugging — When an agent makes a mistake, you can replay the exact session from your database, test a different tool call sequence without re-booting infrastructure, and redeploy in seconds.

The Infrastructure Problem: Why It's Hard

Building this pattern requires:

Durable session state — Every tool call, every output, every decision needs to persist across sandbox deaths. Postgres, not ephemeral memory.
Tool coordination — Brain needs to know what tools the sandbox exposes, validate tool calls before execution, bind credentials at invocation time (not in the sandbox).
Memory management — Session state can grow (100+ tool calls per session). You need efficient storage, not just concatenating everything into the context window.
Multi-runtime abstraction — If you swap Claude for Cursor for Bedrock, the session and credentials need to follow. That's a control plane problem, not a framework problem.

Most agent frameworks (LangGraph, CrewAI, Anthropic SDK) handle the logic layer beautifully. None of them provide the infrastructure layer for durable sessions, ephemeral sandboxes, or multi-runtime coordination natively.

That's why teams either:

Path A: Build it themselves (3-6 months, fragile, one runtime)

Path B: Bolt control planes onto frameworks (hacky, undermines performance benefits)

Path C: Use purpose-built control plane infrastructure (LiteLLM Agent Platform, fast to production)

Evaluation: Does Your Agent Infrastructure Support This?

Ask these five questions:

Does the brain run separately from the sandbox? (If not, you're paying sandbox time for thinking.)
Can sessions survive sandbox restarts? (If not, multi-file edits restart context from scratch.)
Can you swap runtimes without rewriting agents? (If not, you're locked in.)
Do tool calls execute immediately, or do they re-invoke the model first? (One round-trip vs. two = 2x latency difference.)
Is session history durable and queryable? (If not, debugging and replay are manual.)

If your answers are "no," you're probably hitting the multi-file task wall soon.

What Production Agents Actually Need

By July 2026, the pattern is clear: teams building reliable coding agents separate concerns:

Brain layer — LiteLLM Agent Platform manages sessions, credentials, tool decisions
Sandbox layer — Fast, lightweight, ephemeral (E2B, Daytona, custom)
Gateway layer — LiteLLM-Rust routes tool calls with sub-1ms overhead, so sandbox transitions don't add latency
Observability layer — Every tool call, every decision, every error is logged durably

The agents that ship actual code don't have the smartest models or the most autonomous behavior. They have the most boring, most reliable infrastructure. Separated layers. Durable state. Fast feedback loops.

Your coding agent isn't broken. Your sandbox architecture probably is.

What's your agent's sandbox architecture looking like? Are you hitting the multi-file wall? Drop a comment—I'm curious what patterns you're seeing in production.