Plan Mode
Relevant source files
The following files were used as context for generating this wiki page:
Plan Mode is a specialized execution state in QQcode where the AI agent explores and analyzes a codebase to formulate a strategy without making any modifications. In this mode, the agent's tool access is strictly limited to read-only operations, ensuring that the project state remains untouched while the agent gathers the necessary context to fulfill a user request.
Once the agent has developed a comprehensive understanding, it generates an implementation plan in Markdown format and submits it for user review via the submit_plan tool. The user then decides whether to approve the plan (transitioning into an active implementation mode), request revisions, or remain in Plan Mode for further exploration.
Sources: vibe/core/prompts/plan_mode.md:1-10, vibe/core/tools/builtins/plan_mode.py:42-46
Architecture and Core Logic
Plan Mode is implemented through a combination of system prompt injection, tool restriction logic, and a specialized approval workflow. When the agent is initialized or switched into Plan Mode, the system prompt is regenerated to include specific instructions and constraints.
System Prompt Integration
The system prompt acts as the primary enforcement mechanism for Plan Mode. It explicitly defines the agent's status, available tools, and the required output format for plans.
The get_universal_system_prompt function checks the active mode and appends the content of vibe/core/prompts/plan_mode.md when applicable. This ensures the agent is aware of its read-only status and the requirement to use submit_plan.
Sources: vibe/core/system_prompt.py:311-314, tests/test_plan_mode_system_prompt.py:48-55
Tool Restrictions
In Plan Mode, the agent is restricted to a subset of tools. Write-capable tools are blocked, and shell execution is filtered for safety.
| Category | Allowed Tools/Commands | Blocked Operations |
|---|---|---|
| Built-in Tools | read_file, grep, todo, bash, submit_plan | write_file, edit |
| Bash Commands | ls, cat, find, tree, git log, grep | rm, mkdir, touch, git commit, pip |
Sources: vibe/core/prompts/plan_mode.md:13-33
Plan Submission and Approval Workflow
The transition from planning to execution is governed by the submit_plan tool and associated UI widgets in the CLI and VS Code extension.
The SubmitPlan Tool
The SubmitPlan class takes a Markdown string as an argument. Its execution returns a result indicating that the plan is awaiting user approval.
class SubmitPlanArgs(BaseModel):
plan: str = Field(description="The implementation plan in Markdown format")
class SubmitPlanResult(BaseModel):
success: bool
message: str
plan_submitted: Literal[True] = True
approved: bool | None = None
execution_mode: str | None = None
Sources: vibe/core/tools/builtins/plan_mode.py:22-31
Approval Sequence
Once a plan is submitted, the system halts autonomous execution and presents the user with several options.
User Interface Implementation
CLI (Textual UI)
In the CLI, the PlanApprovalWidget handles the interaction. It provides keyboard shortcuts (1, 2, 3, or R) and a specialized revision input field.
- Execute (Auto): Transitions to
AgentMode.AUTO_APPROVE. - Execute (Manual): Transitions to
AgentMode.INTERACTIVE. - Revise Plan: Opens an input field to collect user feedback.
Sources: vibe/cli/textual_ui/widgets/plan_approval.py:16-25, vibe/cli/textual_ui/widgets/plan_approval.py:127-147
VS Code Extension
The webview interface in the VS Code extension uses chat.js to render the plan and capture responses. It supports a "Revision Mode" where users can provide feedback to improve the plan before execution begins.
function showPlanApproval(plan) {
// ... renders plan as Markdown ...
// Options: Execute with Auto-Approve, Execute with Manual Approval, Revise Plan
}
Sources: vscode-extension/media/webview/chat.js:763-808, vscode-extension/src/chatView/ChatViewProvider.ts:503-518
Transitioning to Implementation
After a plan is approved, the agent must formally exit Plan Mode. The ExitPlanMode tool is used to acknowledge the transition. This tool's primary purpose is to signal that the agent has moved from the planning phase into the implementation phase, where write-access tools are re-enabled.
Sources: vibe/core/tools/builtins/plan_mode.py:68-82
Plan Mode serves as a critical safety and architectural boundary in QQcode, ensuring that complex changes are thoroughly analyzed and user-vetted before a single line of code is modified.