{"slug": "how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state", "title": "How AIClaw Keeps Agent Plans Out of Chat History with Runtime Plan State", "summary": "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.", "body_md": "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.\n\nAIClaw 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.\n\nThis 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.\n\nIf an agent writes plans directly into chat, several issues show up quickly:\n\nAIClaw's approach is to separate these concerns:\n\nThe 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.\n\nAt a high level, AIClaw's execution loop does this:\n\nThe plan has a small lifecycle instead of being treated like free-form prose:\n\n``` php\npending -> running -> completed\n                  -> failed\n                  -> blocked\npending -> skipped\n```\n\nThat lifecycle matters because the harness can enforce behavior the model should not be trusted to enforce by itself.\n\nIn [ internal/agent/plan.go](https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/internal/agent/plan.go), the internal\n\n`plan`\n\ncontrol tool supports actions such as `set`\n\n, `update`\n\n, `revise`\n\n, and `read`\n\n. But the important part is not the tool surface. The important part is ownership:`PlanManager`\n\nnormalizes and validates stateThat split keeps the model flexible without giving it full control over task state.\n\nFor example, AIClaw enforces that only one plan item can be `running`\n\nat 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\n\n`running`\n\n, 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.\n\nThe `PromptBlock`\n\npath in [ internal/agent/plan.go](https://dev.to/Users/yu/go/src/github.com/chowyu12/aiclaw/internal/agent/plan.go) builds a compact\n\n`<plan_state>`\n\nblock 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.\n\nThis 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.\n\nThe 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.\n\nThat behavior is also covered by tests:\n\n`running`\n\nThis is the difference between \"the model wrote a checklist\" and \"the system is actually operating a task state machine.\"\n\nFrom the product side, Runtime Plan State gives AIClaw a cleaner split between response and observability:\n\nThat 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.\n\nImagine an AIClaw agent is asked to:\n\nWith 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.\n\nThat is a better fit for production-style agent work than chat-visible TODO spam.\n\nAIClaw's design makes a strong distinction:\n\nThose should not all be the same thing.\n\nA lot of agent systems blur the line between them. AIClaw's Runtime Plan State is interesting precisely because it does not.\n\nIf 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.\n\nAIClaw is open source here: [github.com/chowyu12/aiclaw](https://github.com/chowyu12/aiclaw)", "url": "https://wpnews.pro/news/how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state", "canonical_source": "https://dev.to/chowyu12/how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state-ib5", "published_at": "2026-06-13 16:35:21+00:00", "updated_at": "2026-06-13 17:15:24.360880+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["AIClaw"], "alternates": {"html": "https://wpnews.pro/news/how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state", "markdown": "https://wpnews.pro/news/how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state.md", "text": "https://wpnews.pro/news/how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state.txt", "jsonld": "https://wpnews.pro/news/how-aiclaw-keeps-agent-plans-out-of-chat-history-with-runtime-plan-state.jsonld"}}