How AIClaw Keeps Agent Plans Out of Chat History with Runtime Plan State

AIClaw's Runtime Plan State feature keeps agent plans out of chat history by treating them as runtime state owned by the executor. The system validates, persists, and streams the plan separately from the assistant message, preventing the final answer from being buried under noisy TODO updates. This design enforces a plan lifecycle and injects only a compact summary into each model call to conserve context budget.

Most agent products eventually hit the same UX problem: complex tasks need planning, but users do not want the final answer buried under noisy TODO updates. AIClaw handles that with an existing core feature called Runtime Plan State . Instead of storing planning as ordinary assistant text, AIClaw treats the plan as runtime state owned by the executor. The model can propose or revise a plan, but the harness validates it, persists it, streams it live, and links the final snapshot to the assistant message after execution finishes. This post is not announcing a brand-new feature. It is a deeper look at how AIClaw already implements planning in a way that stays useful during execution without polluting the conversation itself. If an agent writes plans directly into chat, several issues show up quickly: AIClaw's approach is to separate these concerns: The repository README describes this directly: AIClaw uses Plan State instead of chat-visible TODO blocks, and streaming chat plus execution logs show the plan separately from the assistant answer. At a high level, AIClaw's execution loop does this: The plan has a small lifecycle instead of being treated like free-form prose: php pending - running - completed - failed - blocked pending - skipped That lifecycle matters because the harness can enforce behavior the model should not be trusted to enforce by itself. In internal/agent/plan.go https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/internal/agent/plan.go , the internal plan control tool supports actions such as set , update , revise , and read . But the important part is not the tool surface. The important part is ownership: PlanManager normalizes and validates stateThat split keeps the model flexible without giving it full control over task state. For example, AIClaw enforces that only one plan item can be running at a time. The tests in internal/agent/plan test.go https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/internal/agent/plan test.go explicitly verify that if multiple items are proposed as running , the plan is normalized back to a single running item.One subtle but important implementation detail is that AIClaw does not inject the full plan history into every model call. The PromptBlock path in internal/agent/plan.go https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/internal/agent/plan.go builds a compact <plan state block with:The design notes in docs/design/agent-improvements.md https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/docs/design/agent-improvements.md call this out clearly: only the goal, current running item, remaining pending summary, and recent revision reason are injected each round so the full history does not consume context budget. This is a practical design choice. Planning helps the model stay oriented, but dumping the whole plan transcript back into the prompt every round would work against that goal. The main run loop in internal/agent/run.go https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/internal/agent/run.go refreshes plan state before each model call. When tool or LLM work fails, the harness can mark the current step as failed. When a step succeeds, the harness can complete it and advance to the next pending one. That behavior is also covered by tests: running This is the difference between "the model wrote a checklist" and "the system is actually operating a task state machine." From the product side, Runtime Plan State gives AIClaw a cleaner split between response and observability: That matters for real tool-using agents. If an agent reads files, runs commands, searches the web, or delegates to sub-agents, users need to inspect progress and failures without turning the final answer into a debug trace. Imagine an AIClaw agent is asked to: With Runtime Plan State, the plan can exist as structured execution state while the tool timeline records the underlying work. If the test step fails, AIClaw can mark that step as failed and continue the state transition logic cleanly. If the work completes, the final answer can stay focused on outcome, not internal bookkeeping. That is a better fit for production-style agent work than chat-visible TODO spam. AIClaw's design makes a strong distinction: Those should not all be the same thing. A lot of agent systems blur the line between them. AIClaw's Runtime Plan State is interesting precisely because it does not. If you are building self-hosted agents and want both cleaner chat UX and better execution observability, this is one of the AIClaw features worth studying in the codebase. AIClaw is open source here: github.com/chowyu12/aiclaw https://github.com/chowyu12/aiclaw