Artificial Intelligence · Agent · AI Programming

Plan Mode Is a State Machine, Not a Prompt

By 不一样的少年_ · Aug 18, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Prompt-based guardrails are unreliable; a model with write access can still modify files. A Harness-enforced Plan Mode creates a real permission boundary, preventing premature code changes and making AI agents safe for unsupervised project exploration.

Summary

Giving an AI agent write access from the start lets it modify code before understanding the full picture—deleting compatibility layers, missing real entry points, and skipping tests. The solution is not a polite prompt asking it to think first, but a Harness-level state machine that physically removes write tools during the planning phase. The agent can only read files, list directories, and search code until it submits a structured plan. The Agent Loop then pauses entirely, waiting for a human to approve, request changes, or cancel. Only after approval are write tools restored, and the agent begins executing against a generated TODO checklist. This three-phase cycle—planning, approval, execution—turns an eager code modifier into a disciplined engineering collaborator.

Takeaways

— Plan Mode is a Harness-controlled state machine, not a system prompt asking the model to think first.

— During planning, the agent can only use read_file, list_files, search_files, and submit_plan; write_file, edit_file, and bash are hidden from the model and blocked by the tool registry.

— Calling submit_plan switches the agent state to waiting_for_approval and pauses the Agent Loop until the user chooses to approve, modify, or cancel.

— Approval creates a task directory with a stable PLAN.md and an executable TODO.md, isolating each task's artifacts.

— Plan and TODO serve different purposes: the plan is a stable, approved proposal; the TODO is a live execution checklist updated as steps complete.

— Bash is excluded from Plan Mode to avoid the complexity of distinguishing safe read-only commands from destructive ones.

— The /code command is an escape hatch to return to normal mode without approving a plan, while "Approve and Execute" formalizes the plan and generates task files.

Conclusions

Separating mode (which tools are available) from status (what phase the loop is in) is critical; a single boolean cannot distinguish between actively planning and waiting for approval.

Structuring the plan into title, content, and steps lets the Harness automate task directory creation and TODO generation without parsing free-form Markdown.

Using a dedicated submit_plan tool turns an ambiguous model output into an explicit workflow event the Harness can act on.

Even read-only tools must enforce path sandboxing; read-only does not mean the agent can read arbitrary files on the user's system.

Task directory names must be sanitized from model-generated titles to prevent path traversal and collisions.

Concepts & terms

Plan Mode

An agent state where write and execution tools are removed, forcing the model to only explore the project and submit a plan for human approval before any code changes.

Agent Loop

The core execution cycle where the model receives context, chooses tools, and processes results. The loop must be designed to pause at specific states, like waiting for plan approval.

Harness

The controlling infrastructure around the AI model that manages state, tool availability, and workflow pauses, as opposed to relying solely on prompts for behavior control.

submit_plan

A dedicated tool that acts as an explicit 'planning complete' event, allowing the Harness to transition the agent from the planning state to the waiting-for-approval state and pause the loop.

State Machine

A model of computation where the system can be in exactly one of a finite number of states at any time, with defined transitions between them. Here, it governs the agent's mode (plan/code) and status (planning/waiting/executing).

Source: juejin.cn ↗ Google Translate ↗ Backup ↗