Agent Context Management: What Actually Gets Passed On

An investigation step finds the cause of a broken build, then prints pages of test output on its way to the fix. The next agent receives the latest scroll, discusses progress prompts, and misses the cause entirely. Nothing has crashed. Both agents ran. The handoff failed.

Model context windows have grown by orders of magnitude over the past few years, and the problem remains exactly where it started. A larger window still fills, and selection still decides whether the next step receives evidence or noise.

A handoff is a cut, not a pipe

AuricIDE treats each handoff as a choice about what deserves to cross the boundary between two agents.

A terminal is built for watching a process. It redraws spinners, adds colors, repeats status lines, and prints controls for the person at the keyboard. Those details helped during the first step. They do not explain its conclusion. A raw transcript gives every line equal weight, so recent display activity can displace the one earlier finding that still matters.

The result looks healthy. Step two starts on time. Its answer may even sound confident. But its conversation begins with material arranged for a screen, not for the decision it must make next. That failure is quiet, which makes it harder to spot than a crashed process.

Practical rule: A handoff should preserve the previous step's actionable result, not its entire performance.

That distinction matters across AI agent workflows. Agent context management begins with a plain question: what should the next process be allowed to forget?

What does AuricIDE give the next agent?

AuricIDE gives the next combo step its own instructions plus a cleaned tail from the previous step's terminal.

A combo is an ordered set of skills. Each step selects an agent provider, model, prompt, and permission mode. One step can inspect a project without write access. The next can make the approved change. Each runs as a separate local process, so the new step does not inherit a hidden conversation from the old one.

The handoff follows a fixed sequence. First, AuricIDE joins only recent captured output. It normalizes line endings. ANSI color and cursor codes go. Blank redraws shrink. Lines without words disappear. Known interface chrome, including progress displays and control prompts, is filtered. Consecutive duplicate bodies collapse. The remaining lines keep their order.

Then comes the hard cut.

AuricIDE counts backward from the newest cleaned line until the 2,000-character budget is spent. It stops at a line boundary. Older lines disappear first. If one final line alone exceeds the whole budget, AuricIDE keeps that line's end with a leading ellipsis. That narrow exception avoids returning nothing.

The next process sees this material under a label that calls it a terminal tail. The prompt also warns that it may be incomplete and may still contain interface noise. The step must check the working tree before trusting it. This is a lead, not a record.

The output passed onward is therefore a cleaned tail of terminal output, never raw stdout and never a full log. It is also not a summary. No model decides what mattered. Cleanup removes known noise, while position decides which useful lines survive.

AuricIDE stops the combo when a step fails. Failure itself collapses to three values: a clean exit becomes 0 and Idle, any nonzero exit becomes 1 and Error, a wait error becomes -1 and Error, never the process's raw numeric exit code. Later prompts assume that earlier work succeeded, so running them past a failed step would spend tokens inside a false state. Success starts the next process with its own provider, model, permissions, and prompt, and the tail is added as context.

Retrieval-augmented generation, introduced by Lewis and colleagues in 2020, combined model knowledge with external information rather than forcing all material into one prompt, as summarized in this history of retrieval-augmented generation. A small, selected working set can be more useful than a large undifferentiated record. AuricIDE applies that principle to terminal output, as part of its LLM orchestration tools.

Which context should survive the handoff?

Project decisions should survive in MCP state, while the terminal tail should carry only the previous step's recent report.

These channels answer different questions. The tail says what just happened. Project state says what remains, which work is blocked, and what later sessions must still know. Mixing them makes a passing test look permanent and lets a real requirement vanish with old terminal output.

AuricIDE exposes goals, tickets, requirements, dependencies, test cases, and history through MCP. The project data sits in a SQLite file at <project>/.auric/project.db. AuricIDE puts a .gitignore containing * inside that directory, so the records stay on that machine. A clone brings no work record with it.

Keeping state inside each project directory prevents one open repository from supplying another repository's tickets to an agent by accident. A linked worktree resolves back to the main checkout's database. Its agents use the same project record.

The broader design is described in the MCP server implementation overview.

Focused MCP tools reduce what an agent must load. For example, get_unfinished_tickets_overview takes no parameters and groups unfinished tickets by epic. It includes dependent counts and blocking dependency names. The agent can choose work without reading every ticket.

A ticket belongs here. So does a requirement. A transient test failure belongs in the tail unless someone records it as a durable finding. The boundary requires judgment, but the storage roles stay clear.

What does the 2,000-character cut cost?

The fixed cap can delete the most important line, because it selects by recency rather than meaning.

Suppose a command reports its failure first. Tests continue. Status lines follow. Cleanup removes known chrome and duplicates, but valid later output still consumes the budget. The early diagnosis falls outside the tail. The next agent cannot recover it from that channel.

This is deliberate loss. A larger cap preserves more history, yet it also gives incidental output more room to compete with the result that matters. A smaller cap would sharpen the handoff and drop useful details sooner. Character count cannot measure importance.

The rule changes how a combo step should finish. Put the verdict near the end. Name the failing test. State the file or decision that matters. Keep diagnostic output above it. A short closing report gives the next process a stable target without pretending the preceding transcript was worthless.

Put the conclusion at the end when the next reader receives the tail.

That requirement is annoying. Command authors must write for a downstream model and for the person watching the terminal. The benefit is inspectability: the handoff rule is simple enough to test, explain, and notice when it loses the wrong detail.

What should hold in any multi-agent tool?

Every multi-agent tool should make its retention boundary visible, even when its handoff uses a different mechanism.

The mechanism might be a tail, summary, file reference, database record, or selected conversation turn. The names matter less than the decisions. Where is the cut? What gets filtered? Which facts persist? What stops later work after a failed step?

AuricIDE answers those questions with a cleaned terminal tail, repository-scoped MCP state, and separate local processes. Visit AuricIDE to examine how that separation fits a multi-agent workflow before choosing what should cross its next boundary.

The useful review is concrete. Inspect what reaches step two. Force step one to print noise after an early finding. Check whether failure stops the chain. Restart the tool and see which decisions remain. Then decide whether the surviving context helps the next agent act.

More context is not the goal.

A reliable handoff preserves the right evidence, labels what may be incomplete, and gives durable decisions somewhere else to remain.