feat: add propose_plan tool for markdown plan proposals (#23452)

Adds a `propose_plan` tool that presents a workspace markdown file as a
dedicated plan card in the agent UI.

The workflow is: the agent uses `write_file`/`edit_files` to build a
plan file (e.g. `/home/coder/PLAN.md`), then calls `propose_plan(path)`
to present it. The backend reads the file via `ReadFile` and the
frontend renders it as an expanded markdown preview card.

**Backend** (`coderd/x/chatd/chattool/proposeplan.go`): new tool
registered as root-chat-only. Validates `.md` suffix, requires an
absolute path, reads raw file content from the workspace agent. Includes
1 MiB size cap.

**Frontend** (`site/src/components/ai-elements/tool/`): dedicated
`ProposePlanTool` component with `ToolCollapsible` + `ScrollArea` +
`Response` markdown renderer, expanded by default. Custom icon
(`ClipboardListIcon`) and filename-based label.

**System prompt** (`coderd/x/chatd/prompt.go`): added `<planning>`
section guiding the agent to research → write plan file → iterate → call
`propose_plan`.

coderd/x/chatd/chatd.go

@@ -3334,6 +3334,7 @@ func (p *Server) runChat(
 	// create workspaces or spawn further subagents — they should
 	// focus on completing their delegated task.
 	if !chat.ParentChatID.Valid {
+		// Workspace provisioning tools.
 		tools = append(tools,
 			chattool.ListTemplates(chattool.ListTemplatesOptions{
 				DB:      p.db,
@@ -3361,6 +3362,37 @@ func (p *Server) runChat(
 				WorkspaceMu: &workspaceMu,
 			}),
 		)
+		// Plan presentation tool.
+		tools = append(tools, chattool.ProposePlan(chattool.ProposePlanOptions{
+			GetWorkspaceConn: workspaceCtx.getWorkspaceConn,
+			StoreFile: func(ctx context.Context, name string, mediaType string, data []byte) (uuid.UUID, error) {
+				workspaceCtx.chatStateMu.Lock()
+				chatSnapshot := *workspaceCtx.currentChat
+				workspaceCtx.chatStateMu.Unlock()
+
+				if !chatSnapshot.WorkspaceID.Valid {
+					return uuid.Nil, xerrors.New("chat has no workspace")
+				}
+
+				ws, err := p.db.GetWorkspaceByID(ctx, chatSnapshot.WorkspaceID.UUID)
+				if err != nil {
+					return uuid.Nil, xerrors.Errorf("resolve workspace: %w", err)
+				}
+
+				row, err := p.db.InsertChatFile(ctx, database.InsertChatFileParams{
+					OwnerID:        chatSnapshot.OwnerID,
+					OrganizationID: ws.OrganizationID,
+					Name:           name,
+					Mimetype:       mediaType,
+					Data:           data,
+				})
+				if err != nil {
+					return uuid.Nil, xerrors.Errorf("insert chat file: %w", err)
+				}
+
+				return row.ID, nil
+			},
+		}))
 		tools = append(tools, p.subagentTools(ctx, func() database.Chat {
 			return chat
 		})...)

coderd/x/chatd/chatd_test.go

@@ -218,7 +218,7 @@ func TestSubagentChatExcludesWorkspaceProvisioningTools(t *testing.T) {
 	require.GreaterOrEqual(t, len(recorded), 2,
 		"expected at least 2 streamed LLM calls (root + subagent)")
 
-	workspaceTools := []string{"list_templates", "read_template", "create_workspace"}
+	workspaceTools := []string{"propose_plan", "list_templates", "read_template", "create_workspace"}
 	subagentTools := []string{"spawn_agent", "wait_agent", "message_agent", "close_agent"}
 
 	// Identify root and subagent calls. Root chat calls include

coderd/x/chatd/chattool/proposeplan.go

@@ -0,0 +1,92 @@
+package chattool
+
+import (
+	"context"
+	"io"
+	"path/filepath"
+	"strings"
+
+	"charm.land/fantasy"
+	"github.com/google/uuid"
+
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+)
+
+const maxProposePlanSize = 32 * 1024 // 32 KiB
+
+// ProposePlanOptions configures the propose_plan tool.
+type ProposePlanOptions struct {
+	GetWorkspaceConn func(context.Context) (workspacesdk.AgentConn, error)
+	StoreFile        func(ctx context.Context, name string, mediaType string, data []byte) (uuid.UUID, error)
+}
+
+// ProposePlanArgs are the arguments for the propose_plan tool.
+type ProposePlanArgs struct {
+	Path string `json:"path"`
+}
+
+// ProposePlan returns a tool that presents a Markdown plan file from the
+// workspace for user review.
+func ProposePlan(options ProposePlanOptions) fantasy.AgentTool {
+	return fantasy.NewAgentTool(
+		"propose_plan",
+		"Present a Markdown plan file from the workspace for user review. "+
+			"The file must already exist with a .md extension — use write_file to create it or edit_files to refine it before calling this tool. "+
+			"Pass the absolute file path (e.g. /home/coder/PLAN.md). The tool reads the content from the workspace.",
+		func(ctx context.Context, args ProposePlanArgs, _ fantasy.ToolCall) (fantasy.ToolResponse, error) {
+			if options.GetWorkspaceConn == nil {
+				return fantasy.NewTextErrorResponse("workspace connection resolver is not configured"), nil
+			}
+			if options.StoreFile == nil {
+				return fantasy.NewTextErrorResponse("file storage is not configured"), nil
+			}
+			conn, err := options.GetWorkspaceConn(ctx)
+			if err != nil {
+				return fantasy.NewTextErrorResponse(err.Error()), nil
+			}
+			return executeProposePlanTool(ctx, conn, args, options.StoreFile)
+		},
+	)
+}
+
+func executeProposePlanTool(
+	ctx context.Context,
+	conn workspacesdk.AgentConn,
+	args ProposePlanArgs,
+	storeFile func(ctx context.Context, name string, mediaType string, data []byte) (uuid.UUID, error),
+) (fantasy.ToolResponse, error) {
+	path := strings.TrimSpace(args.Path)
+	if path == "" {
+		return fantasy.NewTextErrorResponse("path is required (use an absolute path, e.g. /home/coder/PLAN.md)"), nil
+	}
+	if !strings.HasSuffix(path, ".md") {
+		return fantasy.NewTextErrorResponse("path must end with .md"), nil
+	}
+
+	rc, _, err := conn.ReadFile(ctx, path, 0, maxProposePlanSize+1)
+	if err != nil {
+		return fantasy.NewTextErrorResponse(err.Error()), nil
+	}
+	defer rc.Close()
+
+	data, err := io.ReadAll(rc)
+	if err != nil {
+		return fantasy.NewTextErrorResponse(err.Error()), nil
+	}
+	if int64(len(data)) > maxProposePlanSize {
+		return fantasy.NewTextErrorResponse("plan file exceeds 32 KiB size limit"), nil
+	}
+
+	fileID, err := storeFile(ctx, filepath.Base(path), "text/markdown", data)
+	if err != nil {
+		return fantasy.NewTextErrorResponse("failed to store plan file: " + err.Error()), nil
+	}
+
+	return toolResponse(map[string]any{
+		"ok":         true,
+		"path":       path,
+		"kind":       "plan",
+		"file_id":    fileID.String(),
+		"media_type": "text/markdown",
+	}), nil
+}

coderd/x/chatd/chattool/proposeplan_test.go

@@ -0,0 +1,309 @@
+package chattool_test
+
+import (
+	"context"
+	"encoding/json"
+	"io"
+	"strings"
+	"testing"
+	"testing/iotest"
+
+	"charm.land/fantasy"
+	"github.com/google/uuid"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/mock/gomock"
+	"golang.org/x/xerrors"
+
+	"github.com/coder/coder/v2/coderd/x/chatd/chattool"
+	"github.com/coder/coder/v2/codersdk/workspacesdk"
+	"github.com/coder/coder/v2/codersdk/workspacesdk/agentconnmock"
+)
+
+type proposePlanResponse struct {
+	OK        bool   `json:"ok"`
+	Path      string `json:"path"`
+	Kind      string `json:"kind"`
+	FileID    string `json:"file_id"`
+	MediaType string `json:"media_type"`
+}
+
+func TestProposePlan(t *testing.T) {
+	t.Parallel()
+
+	t.Run("EmptyPathReturnsError", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":""}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "path is required")
+	})
+
+	t.Run("WhitespaceOnlyPathReturnsError", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"  "}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "path is required")
+	})
+
+	t.Run("NonMdPathReturnsError", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/plan.txt"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "path must end with .md")
+	})
+
+	t.Run("OversizedFileRejected", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+		largeContent := strings.Repeat("x", 32*1024+1)
+
+		mockConn.EXPECT().
+			ReadFile(gomock.Any(), "/home/coder/PLAN.md", int64(0), int64(32*1024+1)).
+			Return(io.NopCloser(strings.NewReader(largeContent)), "text/markdown", nil)
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "plan file exceeds 32 KiB size limit")
+	})
+
+	t.Run("ExactBoundaryFileSucceeds", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+		content := strings.Repeat("x", 32*1024)
+
+		mockConn.EXPECT().
+			ReadFile(gomock.Any(), "/home/coder/PLAN.md", int64(0), int64(32*1024+1)).
+			Return(io.NopCloser(strings.NewReader(content)), "text/markdown", nil)
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.False(t, resp.IsError)
+	})
+
+	t.Run("ValidPlanReadsFile", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		mockConn.EXPECT().
+			ReadFile(gomock.Any(), "/home/coder/docs/PLAN.md", int64(0), int64(32*1024+1)).
+			Return(io.NopCloser(strings.NewReader("# Plan\n\nContent")), "text/markdown", nil)
+
+		storeFile, stored := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/docs/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.False(t, resp.IsError)
+
+		result := decodeProposePlanResponse(t, resp)
+		assert.True(t, result.OK)
+		assert.Equal(t, "/home/coder/docs/PLAN.md", result.Path)
+		assert.Equal(t, "plan", result.Kind)
+		assert.Equal(t, "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", result.FileID)
+		assert.Equal(t, "text/markdown", result.MediaType)
+		assert.Equal(t, []byte("# Plan\n\nContent"), *stored)
+		assert.NotContains(t, resp.Content, "content")
+	})
+
+	t.Run("FileNotFound", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		mockConn.EXPECT().
+			ReadFile(gomock.Any(), "/home/coder/PLAN.md", int64(0), int64(32*1024+1)).
+			Return(nil, "", xerrors.New("file not found"))
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "file not found")
+	})
+
+	t.Run("ReadAllError", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		mockConn.EXPECT().
+			ReadFile(gomock.Any(), "/home/coder/PLAN.md", int64(0), int64(32*1024+1)).
+			Return(io.NopCloser(iotest.ErrReader(xerrors.New("connection reset"))), "text/markdown", nil)
+
+		storeFile, _ := fakeStoreFile(t)
+		tool := newProposePlanTool(t, mockConn, storeFile)
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "connection reset")
+	})
+
+	t.Run("StoreFileError", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		mockConn.EXPECT().
+			ReadFile(gomock.Any(), "/home/coder/PLAN.md", int64(0), int64(32*1024+1)).
+			Return(io.NopCloser(strings.NewReader("# Plan")), "text/markdown", nil)
+
+		tool := newProposePlanTool(t, mockConn, func(_ context.Context, _ string, _ string, _ []byte) (uuid.UUID, error) {
+			return uuid.Nil, xerrors.New("storage unavailable")
+		})
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "storage unavailable")
+	})
+
+	t.Run("WorkspaceConnectionError", func(t *testing.T) {
+		t.Parallel()
+		storeFile, _ := fakeStoreFile(t)
+		tool := chattool.ProposePlan(chattool.ProposePlanOptions{
+			GetWorkspaceConn: func(context.Context) (workspacesdk.AgentConn, error) {
+				return nil, xerrors.New("connection failed")
+			},
+			StoreFile: storeFile,
+		})
+
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "connection failed")
+	})
+
+	t.Run("NilWorkspaceResolver", func(t *testing.T) {
+		t.Parallel()
+		tool := chattool.ProposePlan(chattool.ProposePlanOptions{})
+
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "workspace connection resolver is not configured")
+	})
+
+	t.Run("NilStoreFile", func(t *testing.T) {
+		t.Parallel()
+		ctrl := gomock.NewController(t)
+		mockConn := agentconnmock.NewMockAgentConn(ctrl)
+
+		tool := chattool.ProposePlan(chattool.ProposePlanOptions{
+			GetWorkspaceConn: func(_ context.Context) (workspacesdk.AgentConn, error) {
+				return mockConn, nil
+			},
+		})
+
+		resp, err := tool.Run(context.Background(), fantasy.ToolCall{
+			ID:    "call-1",
+			Name:  "propose_plan",
+			Input: `{"path":"/home/coder/PLAN.md"}`,
+		})
+		require.NoError(t, err)
+		assert.True(t, resp.IsError)
+		assert.Contains(t, resp.Content, "file storage is not configured")
+	})
+}
+
+func newProposePlanTool(
+	t *testing.T,
+	mockConn *agentconnmock.MockAgentConn,
+	storeFile func(ctx context.Context, name string, mediaType string, data []byte) (uuid.UUID, error),
+) fantasy.AgentTool {
+	t.Helper()
+	return chattool.ProposePlan(chattool.ProposePlanOptions{
+		GetWorkspaceConn: func(_ context.Context) (workspacesdk.AgentConn, error) {
+			return mockConn, nil
+		},
+		StoreFile: storeFile,
+	})
+}
+
+func fakeStoreFile(t *testing.T) (func(ctx context.Context, name string, mediaType string, data []byte) (uuid.UUID, error), *[]byte) {
+	t.Helper()
+
+	var stored []byte
+	return func(_ context.Context, name string, mediaType string, data []byte) (uuid.UUID, error) {
+		assert.NotEmpty(t, name)
+		assert.Equal(t, "text/markdown", mediaType)
+		stored = append([]byte(nil), data...)
+		return uuid.MustParse("aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"), nil
+	}, &stored
+}
+
+func decodeProposePlanResponse(t *testing.T, resp fantasy.ToolResponse) proposePlanResponse {
+	t.Helper()
+
+	var result proposePlanResponse
+	require.NoError(t, json.Unmarshal([]byte(resp.Content), &result))
+	return result
+}

coderd/x/chatd/prompt.go

@@ -13,6 +13,7 @@ You MUST execute AS MANY TOOLS to help the user accomplish their task.
 You are COMFORTABLE with vague tasks - using your tools to collect the most relevant answer possible.
 If a user asks how something works, no matter how vague, you MUST use your tools to collect the most relevant answer possible.
 DO NOT ask the user for clarification - just use your tools.
+If a task is too ambiguous to implement with confidence, or the user asks for a plan, write a plan before implementing. Use propose_plan to present it for review.
 </behavior>
 
 <personality>
@@ -70,4 +71,21 @@ When a user asks for help with a task or there is ambiguity on the objective, al
 - What problems they're trying to solve
 
 Don't assume what needs to be done - collaborate to define the scope together.
-</collaboration>`
+</collaboration>
+
+<planning>
+Propose a plan when:
+- The task is too ambiguous to implement with confidence.
+- The user asks for a plan.
+
+If no workspace is attached to this chat yet, create and start one first using create_workspace and start_workspace.
+Once a workspace is available:
+1. Use spawn_agent and wait_agent to research the codebase and gather context as needed.
+2. Use write_file to create a Markdown plan file in the workspace (e.g. /home/coder/PLAN.md).
+3. Iterate on the plan with edit_files if needed.
+4. Call propose_plan with the absolute file path to present the plan to the user.
+5. Wait for the user to review and approve the plan before starting implementation.
+
+The propose_plan tool reads the file from the workspace — do not pass content directly.
+Write the file first, then present it. All file paths must be absolute.
+</planning>`