feat: add plan mode with restricted tool boundary (#24236)

> This PR was authored by Mux on behalf of Mike.

## Summary
- add persistent plan mode for chats and the chat-specific plan file
flow
- add structured planning tools such as `ask_user_question` and
`propose_plan`
- keep `write_file` and `edit_files` constrained to the chat-specific
plan file during plan turns
- allow shell exploration in plan mode, including subagents, via
`execute` and `process_output`
- block implementation-oriented, provider-native, MCP, dynamic, and
computer-use tools during plan turns
- update the chat UI, tests, and docs for the new planning flow

docs/ai-coder/agents/architecture.md

@@ -149,13 +149,21 @@ workspace connection. Platform and orchestration tools are only available to
 root chats — sub-agents spawned by `spawn_agent` do not have access to them
 and cannot create workspaces or spawn further sub-agents.
 
-| Tool               | What it does                                                                            |
-|--------------------|-----------------------------------------------------------------------------------------|
-| `list_templates`   | Browses available workspace templates, sorted by popularity.                            |
-| `read_template`    | Gets template details and configurable parameters.                                      |
-| `create_workspace` | Creates a workspace from a template and waits for it to be ready.                       |
-| `start_workspace`  | Starts the chat's workspace if it is currently stopped. Idempotent if already running.  |
-| `propose_plan`     | Presents a Markdown plan file from the workspace for user review before implementation. |
+| Tool                | What it does                                                                            |
+|---------------------|-----------------------------------------------------------------------------------------|
+| `list_templates`    | Browses available workspace templates, sorted by popularity.                            |
+| `read_template`     | Gets template details and configurable parameters.                                      |
+| `create_workspace`  | Creates a workspace from a template and waits for it to be ready.                       |
+| `start_workspace`   | Starts the chat's workspace if it is currently stopped. Idempotent if already running.  |
+| `propose_plan`      | Presents a Markdown plan file from the workspace for user review before implementation. |
+| `ask_user_question` | Asks the user structured clarification questions during plan mode.                      |
+
+`propose_plan` and `ask_user_question` are only exposed while plan mode is
+active. In that mode, `write_file` and `edit_files` are restricted to the
+chat-specific plan file, while `execute` and `process_output` remain available
+for exploration such as cloning repositories, searching code, and running
+inspection commands. MCP, dynamic, provider-native, and computer-use tools are
+not available.
 
 ### Orchestration tools
 

docs/ai-coder/agents/index.md

@@ -236,6 +236,7 @@ tasks:
 | `create_workspace`         | Create a workspace from a template                                       |
 | `start_workspace`          | Start a stopped workspace for the current chat                           |
 | `propose_plan`             | Present a Markdown plan file for user review                             |
+| `ask_user_question`        | Ask the user structured clarification questions during plan mode         |
 | `read_file`                | Read file contents from the workspace                                    |
 | `write_file`               | Write a file to the workspace                                            |
 | `edit_files`               | Perform search-and-replace edits across files                            |
@@ -257,7 +258,7 @@ web terminals and IDE access. No additional ports or services are required in
 the workspace.
 
 Platform tools (`list_templates`, `read_template`, `create_workspace`,
-`start_workspace`, `propose_plan`) and orchestration tools (`spawn_agent`,
+`start_workspace`, `propose_plan`, `ask_user_question`) and orchestration tools (`spawn_agent`,
 `wait_agent`, `message_agent`, `close_agent`, `spawn_computer_use_agent`)
 are only available to root chats. Sub-agents do not have access to these
 tools and cannot create workspaces or spawn further sub-agents.
@@ -267,6 +268,41 @@ the virtual desktop feature to be enabled by an administrator.
 `read_skill` and `read_skill_file` are available when the workspace contains
 skills in its `.agents/skills/` directory.
 
+`propose_plan` and `ask_user_question` are only available while plan mode is
+active. In plan mode, the agent can still inspect the workspace and template
+metadata, execute shell commands for exploration, and read process output.
+`write_file` and `edit_files` remain available only for the chat-specific plan
+file under `.coder/plans/`. MCP, dynamic, provider-native, and computer-use
+tools are blocked.
+
+## Plan mode
+
+Plan mode lets you ask the agent to investigate first and present a plan before
+implementation. Open the chat input menu and choose **Plan first** to enable it
+for the current chat. After you enable it, later turns in that chat stay in
+plan mode until you turn it off or click **Implement plan** after a proposed
+plan. Because the mode is stored on the chat, reloading the page preserves the
+current setting.
+
+While plan mode is active:
+
+- the agent can inspect repository files, workspace state, and available
+  templates
+- `write_file` and `edit_files` can only modify the chat-specific plan file
+  under `.coder/plans/`
+- `ask_user_question` can gather structured clarification from the user before
+  a plan is proposed
+- `propose_plan` snapshots the current plan file into the transcript so you can
+  review it before implementation starts
+- `execute` and `process_output` remain available for exploration, such as
+  cloning repositories, searching code, and running inspection commands
+- MCP tools, dynamic tools, provider-native tools, and computer-use tools are
+  not available
+
+This keeps planning turns focused on analysis and plan authoring rather than
+implementation. Once you click **Implement plan**, the next turn runs in normal
+mode again.
+
 ## Comparison to Coder Tasks
 
 Coder Agents is a new approach that differs from

docs/ai-coder/agents/platform-controls/index.md

@@ -55,6 +55,21 @@ commit message formats, preferred libraries, or repository-specific context.
 The system prompt configuration is only accessible to administrators in the
 dashboard. Developers do not see or interact with it.
 
+### Plan mode instructions
+
+Administrators can add deployment-wide instructions that apply only when a chat
+enters plan mode. These instructions supplement the built-in planning behavior
+and are useful for organization-specific planning requirements such as required
+plan sections, approval checkpoints, or review workflows.
+
+This setting is available under **Agents** > **Settings** > **Behavior**.
+Developers do not edit it directly.
+
+The same value is exposed over the experimental chat configuration API:
+
+- `GET /api/experimental/chats/config/plan-mode-instructions`
+- `PUT /api/experimental/chats/config/plan-mode-instructions`
+
 ### Template routing
 
 Platform teams control which templates are available to agents and how the agent