Subagents and context compaction: what long coding agent runs need

A coding agent that works for ten minutes behaves very differently from one that works for three hours. Short runs fit in one context window. Long runs do not, and that is where most of the strange failures come from: the agent forgets a rule you gave it at the start, redoes work it already finished, starts a second dev server, or loses the commit it was supposed to revert.

Two techniques decide whether a long run holds together. Subagents keep side work out of the main conversation. Context compaction replaces old conversation with a summary when the window fills. Both are built into tools like Claude Code and OpenCode. Both also have gaps that show up only on long, real work.

We hit those gaps often enough that we wrote our own versions and published them. This post explains what each technique does, where the defaults fall short, and what we changed. The code is public on our projects page, so you can check every claim against the source.

Anthropic's engineering team describes context as a finite resource with diminishing returns. In its guide to context engineering, it notes that as the number of tokens in the window grows, a model's ability to recall information from that window goes down. It calls this context rot.

For a coding agent, the window fills with things it will never read again: search results, test output, log files, the full text of files it only skimmed. Every one of those tokens competes for attention with the instructions that matter.

The same guide names three ways to work around the limit: compaction, structured note-taking, and sub-agent architectures. Coding tools now ship the first and third by default. The question for a team is whether the defaults hold up on your workloads.

A subagent is a separate agent session that the main agent starts for one task. It has its own context window, its own instructions, and usually a narrower set of tools. It does the work and returns a short report, so the main conversation sees the summary instead of every file read and command run along the way.

Claude Code's subagent documentation puts it plainly: use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again. OpenCode's agent documentation ships two built-in subagents, General for multi-step work and Explore for fast read-only searching, and lets you define your own with their own model and permissions.

Subagents help in three ways:

• Context. The main agent keeps its window for planning and decisions.
• Permissions. A reviewer subagent can be read-only, so it cannot edit what it is reviewing.
• Parallel work. Independent tasks can run side by side.

The usual model is one-way. The parent writes an assignment, the child works in silence, and a report comes back at the end. That works for a quick search. It breaks down on longer tasks:

• The child hits an ambiguity halfway through and has to guess, because it cannot ask.
• The parent learns something new and cannot redirect a child that is already running.
• Two children edit the same checkout and step on each other's changes.
• A batch of five children starts, two fail to launch, and the parent does not notice the gap.

Our OpenCode Smart Subagents plugin replaces OpenCode's built-in subagent tool with a compatible version and adds the missing pieces. According to its README:

• A child can send its parent updates with message_parent and ask questions with ask_parent, and the answer arrives as its next message.
• The parent can steer a running child, answer its question, or hand an idle child its next task.
• Children can list and message their siblings.
• A child that writes code can run in its own git worktree on its own branch, and the parent inspects, merges, cherry-picks, or discards the result.
• subagent_batch starts several background children, and either all of them start or none do.
• A capability input narrows one child to read-only, execute, read-write, or full permissions.

The README also lists the limits honestly. Children cannot start subagents of their own, and the plugin does not cap how many children run at once. Those are deliberate tradeoffs, and a team should know them before relying on the plugin.

Context compaction is what happens when a session nears the end of its window. The tool asks a model to summarize the conversation so far, starts a fresh window with that summary, and keeps going. Anthropic's guide describes it as the first lever for long-run coherence, and warns that overly aggressive compaction can lose subtle details whose importance shows up only later.

That warning matches what we saw. A model-written summary is good at the story of the session and bad at exact state. Typical losses:

• the exact commit SHA, URL, or ID the user pasted;
• a "never do X" rule stated once, early on;
• which files were changed and which were only read;
• what is uncommitted in git right now;
• background shells and subagents that are still running.

When those are lost, the agent after compaction is a different worker with a vague memory. It reruns tests it already ran, restarts servers that are still up, and edits files it should have left alone.

Our OpenCode Smart Compaction plugin, which started as part of our Pi extensions, takes over the summary step. Its README describes the design:

• The model writes a strict six-section checkpoint: goal and constraints, a progress ledger, code changes, errors and fixes, key decisions, and a resume anchor with the next step.
• The plugin checks that all six sections are present in order. If not, it retries, and if every attempt fails, OpenCode compacts with its own prompt. A session never blocks on the plugin.
• Commit SHAs, UUIDs, URLs, and IPv4 addresses from your messages are restored verbatim when the summary drops them.
• File lists come from the session's tool calls, and dirty files and the uncommitted diff come from git, not from the model's memory.
• Running shells and background subagents are listed, so the next turn waits for them instead of starting duplicates.

The general rule behind it: let the model summarize judgment, and let code record facts. Anything the system can read directly, such as git state or tool history, should not depend on a model remembering it.

These two pieces depend on each other. A subagent that keeps running while the parent compacts is easy to forget. A checkpoint that lists running children tells the post-compaction agent to wait for their reports instead of launching the same work again. The subagents plugin keeps the built-in tool's result format for that reason, so the compaction plugin can still read it.

You do not need our plugins to apply the lessons. If your developers run Claude Code, OpenCode, Codex, or Pi on long tasks, a few habits cover most of the risk:

1. 1Delegate noisy work. Searches, test runs, and log reading belong in a subagent that returns a summary.
2. 2Give reviewers read-only access. A reviewing agent should not be able to edit what it reviews.
3. 3Isolate parallel writers. Two agents editing one checkout will conflict. Use worktrees or separate branches.
4. 4Write state down outside the chat. Keep the plan and the rules in a file or task list the agent rereads. The conversation alone will not hold them.
5. 5Check what survives compaction. After a compaction, ask the agent to restate the goal, constraints, and next step before it continues.
6. 6Review the result like any other change. Long agent runs still end in a pull request someone reads. Our post on testing AI agents before production covers the review side.

We build AI agent systems and custom software for small and mid-sized teams, and we use these tools on our own delivery work. When a client's engineers want coding agents to handle longer tasks, we set up the agent configuration, the permission rules, and the review steps, and we leave the setup documented in the client's repository.

If your team is trying long agent runs and getting inconsistent results, start with a free automation audit. We'll look at how the agents are configured, where context is being lost, and what to change first.