One-Line Summary: Adaptive replanning is the discipline of detecting when the current plan no longer fits reality (a tool failed, a precondition was violated, a result surprised the agent) and rebuilding a new plan from the post-divergence state — every long-horizon agent system needs it; the question is how the harness expresses it.
Prerequisites: Goal-oriented action planning, A* planner for agents, plan-and-execute
What Is Adaptive Replanning?
A plan made at t=0 assumes a model of the world. Execution reveals that model was wrong: a search returned no results, a file did not parse, a permission was denied. The agent now has two choices: continue executing a plan that no longer fits (and probably fail), or rebuild the plan from where it actually is. Adaptive replanning is the second.
It is "adaptive" because the agent doesn't replan on a fixed schedule — it replans in response to signals indicating divergence. The signals can be hard (a tool returned an error) or soft (the model expresses doubt; an unexpected piece of state appeared; progress has stalled).
How It Works
Three components:
- Divergence detection: How does the harness know to replan? Hard signals: tool failures, permission denials, exceptions. Soft signals: the agent flags uncertainty, shared state changes unexpectedly, no progress for N turns, cost-per-progress crosses a threshold.
- State extraction: Replanning needs to know "where are we now?" That means inspecting the current world state — file changes made, variables set, partial outputs produced — not just the original starting state.
- Plan regeneration: Re-run the planner (LLM, A*, GOAP) from the current state. Often you can preserve parts of the old plan that are still valid; sometimes you have to start fresh.
Why It Matters
Long-horizon tasks always diverge. The model misjudges; tools return surprising results; the user changes their mind mid-task. Without replanning, agents either execute hopeless plans to completion or cascade into failure. With replanning, the agent stays on track — at the cost of more thinking turns.
The harness's job is to make replanning cheap enough to do often. If replanning costs as much as the original plan, the agent does it reluctantly; if it's cheap, the agent does it whenever divergence is suspected.
Key Technical Details
- Replanning frequency vs. cost: Cheap planners (A* on small action graphs) can replan every turn; expensive planners (LLM chain-of-thought on a 100-step task) replan rarely.
- Preserve what survives: A plan that's still mostly valid should not be discarded. Identify the prefix that already executed correctly, the next-action that failed, and replan from the post-failure state.
- Replanning loops are a failure mode: An agent that replans on every minor signal can fail to make progress. Hysteresis (require K signals before replanning) and a replan budget (max M replans per task) help.
- Soft signals are noisy: LLM-expressed uncertainty is unreliable. Prefer hard signals when possible.
- Goal stability: Replanning assumes the goal didn't change. If the user's intent has shifted, the system should ask, not replan silently.
- Logging matters: Each replan should be logged with what changed and why. This is a major debug artifact for any long-running agent system.
How Harnesses & Frameworks Implement This
| Harness / Framework | Replanning support |
|---|---|
| Claude Code | DIY — agent decides when to replan in chain-of-thought |
| Claude Agent SDK | DIY |
| ruflo | First-class — ruflo-goals triggers replanning on divergence signals |
| LangGraph | DIY — model replan as a graph node that runs conditionally |
| AutoGen | DIY |
| CrewAI | Limited |
| OpenAI Agents SDK | DIY |
| Codex CLI | Implicit via plan mode |
| Cursor | Implicit via agent mode |
Connections to Other Concepts
goal-oriented-action-planning.md,a-star-planner-for-agents.md— The planning substrate.plan-rollback-and-checkpointing.md— Sometimes replanning requires rolling back actions first.multi-step-plan-evaluation.md— How to evaluate whether a replan was justified.../../multi-skill-agent/05-task-decomposition-and-planning/adaptive-replanning.md— Foundational coverage.
Further Reading
- ruvnet, ruflo-goals documentation — Production implementation.