Agent modes (Plan / Act / Ask)
Each chat tab carries an agent mode. The chip in the top-right of the chat surface tells you which one is active and lets you switch.
The mode is sticky per session. A new chat tab starts in Act mode by default and stays there until you change it. Restarting Forge preserves the mode for any chat you reopen.
The three modes
Section titled “The three modes”Full agent. Edits files, runs tasks, calls MCP tools, commits to git when changes are approved. This is the default for power users who want the agent to drive end-to-end.
The agent can read, search, and propose, but it cannot edit files, run shell commands that mutate state, or call MCP tools that write. When it wants to change something, it emits a diff card you review and approve.
Plan mode is also the working surface for .forge/plan.md. The agent sees the current plan body on every turn (capped at 8 KB) and updates it via forge-propose — adding items, ticking them off, or rewording. Forge mints the stable <!-- id: p_xxxxxxxx --> comments at write time; the agent never touches them. See the Plan-mode loop for the full draft → focus → tick flow.
Chat only. The agent doesn’t call any tools, period. No file reads, no shell, no MCP, no apply. Use it for “explain this concept” or “what would you do here” conversations where you don’t want the agent to go investigate.
Ask is the cheapest mode token-wise. The agent isn’t burning tokens on tool calls or file scans, just on the conversation itself.
Switching modes
Section titled “Switching modes”Click the chip in the top-right of the chat surface. The dropdown shows all three modes with a one-line description. Pick one and the chip updates immediately.
The chip’s color reflects the mode: persimmon for Plan, foreground (default) for Act, muted for Ask.
What “soft enforcement” means
Section titled “What “soft enforcement” means”Today, modes are enforced through instructions. When you switch to Plan mode, Forge tells the agent at the start of the next turn: “you are in Plan mode, do not call apply_patch, emit forge-propose-edit blocks instead.”
This works in practice because the underlying model follows the instructions, but it’s not a hard guarantee. Stricter, tool-list-level enforcement is coming soon. Until then, if you spot the agent ignoring its mode, you can switch back to Act and ask it to undo, or revert via the Git tab if it already committed.
When to use which
Section titled “When to use which”- Starting a feature? Plan first to scope the change. Switch to Act once the diff cards look right.
- Stuck on a bug? Plan, then ask for the diagnosis. Switch to Act when you have a fix in mind.
- Learning the codebase? Ask. The agent will explain without poking around.
- Routine work, you trust the agent? Act. Skip the ceremony.