feat(agent): populate subagent ID for terraform-defined devcontainers (#21942)

Completes the final piece of the puzzle. Support the pre-creation flow
from the agent side.

agent/agentcontainers/acmock/acmock.go

@@ -1,9 +1,9 @@
 // Code generated by MockGen. DO NOT EDIT.
-// Source: .. (interfaces: ContainerCLI,DevcontainerCLI)
+// Source: .. (interfaces: ContainerCLI,DevcontainerCLI,SubAgentClient)
 //
 // Generated by this command:
 //
-//	mockgen -destination ./acmock.go -package acmock .. ContainerCLI,DevcontainerCLI
+//	mockgen -destination ./acmock.go -package acmock .. ContainerCLI,DevcontainerCLI,SubAgentClient
 //
 
 // Package acmock is a generated GoMock package.
@@ -15,6 +15,7 @@ import (
 
 	agentcontainers "github.com/coder/coder/v2/agent/agentcontainers"
 	codersdk "github.com/coder/coder/v2/codersdk"
+	uuid "github.com/google/uuid"
 	gomock "go.uber.org/mock/gomock"
 )
 
@@ -216,3 +217,71 @@ func (mr *MockDevcontainerCLIMockRecorder) Up(ctx, workspaceFolder, configPath a
 	varargs := append([]any{ctx, workspaceFolder, configPath}, opts...)
 	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Up", reflect.TypeOf((*MockDevcontainerCLI)(nil).Up), varargs...)
 }
+
+// MockSubAgentClient is a mock of SubAgentClient interface.
+type MockSubAgentClient struct {
+	ctrl     *gomock.Controller
+	recorder *MockSubAgentClientMockRecorder
+	isgomock struct{}
+}
+
+// MockSubAgentClientMockRecorder is the mock recorder for MockSubAgentClient.
+type MockSubAgentClientMockRecorder struct {
+	mock *MockSubAgentClient
+}
+
+// NewMockSubAgentClient creates a new mock instance.
+func NewMockSubAgentClient(ctrl *gomock.Controller) *MockSubAgentClient {
+	mock := &MockSubAgentClient{ctrl: ctrl}
+	mock.recorder = &MockSubAgentClientMockRecorder{mock}
+	return mock
+}
+
+// EXPECT returns an object that allows the caller to indicate expected use.
+func (m *MockSubAgentClient) EXPECT() *MockSubAgentClientMockRecorder {
+	return m.recorder
+}
+
+// Create mocks base method.
+func (m *MockSubAgentClient) Create(ctx context.Context, agent agentcontainers.SubAgent) (agentcontainers.SubAgent, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "Create", ctx, agent)
+	ret0, _ := ret[0].(agentcontainers.SubAgent)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// Create indicates an expected call of Create.
+func (mr *MockSubAgentClientMockRecorder) Create(ctx, agent any) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Create", reflect.TypeOf((*MockSubAgentClient)(nil).Create), ctx, agent)
+}
+
+// Delete mocks base method.
+func (m *MockSubAgentClient) Delete(ctx context.Context, id uuid.UUID) error {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "Delete", ctx, id)
+	ret0, _ := ret[0].(error)
+	return ret0
+}
+
+// Delete indicates an expected call of Delete.
+func (mr *MockSubAgentClientMockRecorder) Delete(ctx, id any) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Delete", reflect.TypeOf((*MockSubAgentClient)(nil).Delete), ctx, id)
+}
+
+// List mocks base method.
+func (m *MockSubAgentClient) List(ctx context.Context) ([]agentcontainers.SubAgent, error) {
+	m.ctrl.T.Helper()
+	ret := m.ctrl.Call(m, "List", ctx)
+	ret0, _ := ret[0].([]agentcontainers.SubAgent)
+	ret1, _ := ret[1].(error)
+	return ret0, ret1
+}
+
+// List indicates an expected call of List.
+func (mr *MockSubAgentClientMockRecorder) List(ctx any) *gomock.Call {
+	mr.mock.ctrl.T.Helper()
+	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "List", reflect.TypeOf((*MockSubAgentClient)(nil).List), ctx)
+}

agent/agentcontainers/acmock/doc.go

@@ -1,4 +1,4 @@
 // Package acmock contains a mock implementation of agentcontainers.Lister for use in tests.
 package acmock
 
-//go:generate mockgen -destination ./acmock.go -package acmock .. ContainerCLI,DevcontainerCLI
+//go:generate mockgen -destination ./acmock.go -package acmock .. ContainerCLI,DevcontainerCLI,SubAgentClient

agent/agentcontainers/api.go

@@ -562,12 +562,9 @@ func (api *API) discoverDevcontainersInProject(projectPath string) error {
 				api.broadcastUpdatesLocked()
 
 				if dc.Status == codersdk.WorkspaceAgentDevcontainerStatusStarting {
-					api.asyncWg.Add(1)
-					go func() {
-						defer api.asyncWg.Done()
-
+					api.asyncWg.Go(func() {
 						_ = api.CreateDevcontainer(dc.WorkspaceFolder, dc.ConfigPath)
-					}()
+					})
 				}
 			}
 			api.mu.Unlock()
@@ -1627,16 +1624,25 @@ func (api *API) cleanupSubAgents(ctx context.Context) error {
 	api.mu.Lock()
 	defer api.mu.Unlock()
 
-	injected := make(map[uuid.UUID]bool, len(api.injectedSubAgentProcs))
+	// Collect all subagent IDs that should be kept:
+	// 1. Subagents currently tracked by injectedSubAgentProcs
+	// 2. Subagents referenced by known devcontainers from the manifest
+	var keep []uuid.UUID
 	for _, proc := range api.injectedSubAgentProcs {
-		injected[proc.agent.ID] = true
+		keep = append(keep, proc.agent.ID)
+	}
+	for _, dc := range api.knownDevcontainers {
+		if dc.SubagentID.Valid {
+			keep = append(keep, dc.SubagentID.UUID)
+		}
 	}
 
 	ctx, cancel := context.WithTimeout(ctx, defaultOperationTimeout)
 	defer cancel()
 
+	var errs []error
 	for _, agent := range agents {
-		if injected[agent.ID] {
+		if slices.Contains(keep, agent.ID) {
 			continue
 		}
 		client := *api.subAgentClient.Load()
@@ -1647,10 +1653,11 @@ func (api *API) cleanupSubAgents(ctx context.Context) error {
 				slog.F("agent_id", agent.ID),
 				slog.F("agent_name", agent.Name),
 			)
+			errs = append(errs, xerrors.Errorf("delete agent %s (%s): %w", agent.Name, agent.ID, err))
 		}
 	}
 
-	return nil
+	return errors.Join(errs...)
 }
 
 // maybeInjectSubAgentIntoContainerLocked injects a subagent into a dev
@@ -2001,7 +2008,20 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 	// 	logger.Warn(ctx, "set CAP_NET_ADMIN on agent binary failed", slog.Error(err))
 	// }
 
-	deleteSubAgent := proc.agent.ID != uuid.Nil && maybeRecreateSubAgent && !proc.agent.EqualConfig(subAgentConfig)
+	// Only delete and recreate subagents that were dynamically created
+	// (ID == uuid.Nil). Terraform-defined subagents (subAgentConfig.ID !=
+	// uuid.Nil) must not be deleted because they have attached resources
+	// managed by terraform.
+	isTerraformManaged := subAgentConfig.ID != uuid.Nil
+	configHasChanged := !proc.agent.EqualConfig(subAgentConfig)
+
+	logger.Debug(ctx, "checking if sub agent should be deleted",
+		slog.F("is_terraform_managed", isTerraformManaged),
+		slog.F("maybe_recreate_sub_agent", maybeRecreateSubAgent),
+		slog.F("config_has_changed", configHasChanged),
+	)
+
+	deleteSubAgent := !isTerraformManaged && maybeRecreateSubAgent && configHasChanged
 	if deleteSubAgent {
 		logger.Debug(ctx, "deleting existing subagent for recreation", slog.F("agent_id", proc.agent.ID))
 		client := *api.subAgentClient.Load()
@@ -2012,11 +2032,23 @@ func (api *API) maybeInjectSubAgentIntoContainerLocked(ctx context.Context, dc c
 		proc.agent = SubAgent{} // Clear agent to signal that we need to create a new one.
 	}
 
-	if proc.agent.ID == uuid.Nil {
-		logger.Debug(ctx, "creating new subagent",
-			slog.F("directory", subAgentConfig.Directory),
-			slog.F("display_apps", subAgentConfig.DisplayApps),
-		)
+	// Re-create (upsert) terraform-managed subagents when the config
+	// changes so that display apps and other settings are updated
+	// without deleting the agent.
+	recreateTerraformSubAgent := isTerraformManaged && maybeRecreateSubAgent && configHasChanged
+
+	if proc.agent.ID == uuid.Nil || recreateTerraformSubAgent {
+		if recreateTerraformSubAgent {
+			logger.Debug(ctx, "updating existing subagent",
+				slog.F("directory", subAgentConfig.Directory),
+				slog.F("display_apps", subAgentConfig.DisplayApps),
+			)
+		} else {
+			logger.Debug(ctx, "creating new subagent",
+				slog.F("directory", subAgentConfig.Directory),
+				slog.F("display_apps", subAgentConfig.DisplayApps),
+			)
+		}
 
 		// Create new subagent record in the database to receive the auth token.
 		// If we get a unique constraint violation, try with expanded names that

agent/agentcontainers/api_test.go

@@ -437,7 +437,11 @@ func (m *fakeSubAgentClient) Create(ctx context.Context, agent agentcontainers.S
 		}
 	}
 
-	agent.ID = uuid.New()
+	// Only generate a new ID if one wasn't provided. Terraform-defined
+	// subagents have pre-existing IDs that should be preserved.
+	if agent.ID == uuid.Nil {
+		agent.ID = uuid.New()
+	}
 	agent.AuthToken = uuid.New()
 	if m.agents == nil {
 		m.agents = make(map[uuid.UUID]agentcontainers.SubAgent)
@@ -1035,6 +1039,30 @@ func TestAPI(t *testing.T) {
 				wantStatus:      []int{http.StatusAccepted, http.StatusConflict},
 				wantBody:        []string{"Devcontainer recreation initiated", "is currently starting and cannot be restarted"},
 			},
+			{
+				name:           "Terraform-defined devcontainer can be rebuilt",
+				devcontainerID: devcontainerID1.String(),
+				setupDevcontainers: []codersdk.WorkspaceAgentDevcontainer{
+					{
+						ID:              devcontainerID1,
+						Name:            "test-devcontainer-terraform",
+						WorkspaceFolder: workspaceFolder1,
+						ConfigPath:      configPath1,
+						Status:          codersdk.WorkspaceAgentDevcontainerStatusRunning,
+						Container:       &devContainer1,
+						SubagentID:      uuid.NullUUID{UUID: uuid.New(), Valid: true},
+					},
+				},
+				lister: &fakeContainerCLI{
+					containers: codersdk.WorkspaceAgentListContainersResponse{
+						Containers: []codersdk.WorkspaceAgentContainer{devContainer1},
+					},
+					arch: "<none>",
+				},
+				devcontainerCLI: &fakeDevcontainerCLI{},
+				wantStatus:      []int{http.StatusAccepted, http.StatusConflict},
+				wantBody:        []string{"Devcontainer recreation initiated", "is currently starting and cannot be restarted"},
+			},
 		}
 
 		for _, tt := range tests {
@@ -2490,6 +2518,338 @@ func TestAPI(t *testing.T) {
 		assert.Empty(t, fakeSAC.agents)
 	})
 
+	t.Run("SubAgentCleanupPreservesTerraformDefined", func(t *testing.T) {
+		t.Parallel()
+
+		var (
+			// Given: A terraform-defined agent and devcontainer that should be preserved
+			terraformAgentID    = uuid.New()
+			terraformAgentToken = uuid.New()
+			terraformAgent      = agentcontainers.SubAgent{
+				ID:        terraformAgentID,
+				Name:      "terraform-defined-agent",
+				Directory: "/workspace",
+				AuthToken: terraformAgentToken,
+			}
+			terraformDevcontainer = codersdk.WorkspaceAgentDevcontainer{
+				ID:              uuid.New(),
+				Name:            "terraform-devcontainer",
+				WorkspaceFolder: "/workspace/project",
+				SubagentID:      uuid.NullUUID{UUID: terraformAgentID, Valid: true},
+			}
+
+			// Given: An orphaned agent that should be cleaned up
+			orphanedAgentID    = uuid.New()
+			orphanedAgentToken = uuid.New()
+			orphanedAgent      = agentcontainers.SubAgent{
+				ID:        orphanedAgentID,
+				Name:      "orphaned-agent",
+				Directory: "/tmp",
+				AuthToken: orphanedAgentToken,
+			}
+
+			ctx    = testutil.Context(t, testutil.WaitMedium)
+			logger = slog.Make()
+			mClock = quartz.NewMock(t)
+			mCCLI  = acmock.NewMockContainerCLI(gomock.NewController(t))
+
+			fakeSAC = &fakeSubAgentClient{
+				logger: logger.Named("fakeSubAgentClient"),
+				agents: map[uuid.UUID]agentcontainers.SubAgent{
+					terraformAgentID: terraformAgent,
+					orphanedAgentID:  orphanedAgent,
+				},
+			}
+		)
+
+		mCCLI.EXPECT().List(gomock.Any()).Return(codersdk.WorkspaceAgentListContainersResponse{
+			Containers: []codersdk.WorkspaceAgentContainer{},
+		}, nil).AnyTimes()
+
+		mClock.Set(time.Now()).MustWait(ctx)
+		tickerTrap := mClock.Trap().TickerFunc("updaterLoop")
+
+		api := agentcontainers.NewAPI(logger,
+			agentcontainers.WithClock(mClock),
+			agentcontainers.WithContainerCLI(mCCLI),
+			agentcontainers.WithSubAgentClient(fakeSAC),
+			agentcontainers.WithDevcontainerCLI(&fakeDevcontainerCLI{}),
+			agentcontainers.WithDevcontainers([]codersdk.WorkspaceAgentDevcontainer{terraformDevcontainer}, nil),
+		)
+		api.Start()
+		defer api.Close()
+
+		tickerTrap.MustWait(ctx).MustRelease(ctx)
+		tickerTrap.Close()
+
+		// When: We advance the clock, allowing cleanup to occur
+		_, aw := mClock.AdvanceNext()
+		aw.MustWait(ctx)
+
+		// Then: The orphaned agent should be deleted
+		assert.Contains(t, fakeSAC.deleted, orphanedAgentID, "orphaned agent should be deleted")
+
+		// And: The terraform-defined agent should not be deleted
+		assert.NotContains(t, fakeSAC.deleted, terraformAgentID, "terraform-defined agent should be preserved")
+		assert.Len(t, fakeSAC.agents, 1, "only terraform agent should remain")
+		assert.Contains(t, fakeSAC.agents, terraformAgentID, "terraform agent should still exist")
+	})
+
+	t.Run("TerraformDefinedSubAgentNotRecreatedOnConfigChange", func(t *testing.T) {
+		t.Parallel()
+
+		if runtime.GOOS == "windows" {
+			t.Skip("Dev Container tests are not supported on Windows (this test uses mocks but fails due to Windows paths)")
+		}
+
+		var (
+			logger = slogtest.Make(t, &slogtest.Options{IgnoreErrors: true}).Leveled(slog.LevelDebug)
+			mCtrl  = gomock.NewController(t)
+
+			// Given: A terraform-defined devcontainer with a pre-assigned subagent ID.
+			terraformAgentID   = uuid.New()
+			terraformContainer = codersdk.WorkspaceAgentContainer{
+				ID:           "test-container-id",
+				FriendlyName: "test-container",
+				Image:        "test-image",
+				Running:      true,
+				CreatedAt:    time.Now(),
+				Labels: map[string]string{
+					agentcontainers.DevcontainerLocalFolderLabel: "/workspace/project",
+					agentcontainers.DevcontainerConfigFileLabel:  "/workspace/project/.devcontainer/devcontainer.json",
+				},
+			}
+			terraformDevcontainer = codersdk.WorkspaceAgentDevcontainer{
+				ID:              uuid.New(),
+				Name:            "terraform-devcontainer",
+				WorkspaceFolder: "/workspace/project",
+				ConfigPath:      "/workspace/project/.devcontainer/devcontainer.json",
+				SubagentID:      uuid.NullUUID{UUID: terraformAgentID, Valid: true},
+			}
+
+			fCCLI = &fakeContainerCLI{
+				containers: codersdk.WorkspaceAgentListContainersResponse{
+					Containers: []codersdk.WorkspaceAgentContainer{terraformContainer},
+				},
+				arch: runtime.GOARCH,
+			}
+
+			fDCCLI = &fakeDevcontainerCLI{
+				upID: terraformContainer.ID,
+				readConfig: agentcontainers.DevcontainerConfig{
+					MergedConfiguration: agentcontainers.DevcontainerMergedConfiguration{
+						Customizations: agentcontainers.DevcontainerMergedCustomizations{
+							Coder: []agentcontainers.CoderCustomization{{
+								Apps: []agentcontainers.SubAgentApp{{Slug: "app1"}},
+							}},
+						},
+					},
+				},
+			}
+
+			mSAC   = acmock.NewMockSubAgentClient(mCtrl)
+			closed bool
+		)
+
+		mSAC.EXPECT().List(gomock.Any()).Return([]agentcontainers.SubAgent{}, nil).AnyTimes()
+
+		// EXPECT: Create is called twice with the terraform-defined ID:
+		// once for the initial creation and once after the rebuild with
+		// config changes (upsert).
+		mSAC.EXPECT().Create(gomock.Any(), gomock.Any()).DoAndReturn(
+			func(_ context.Context, agent agentcontainers.SubAgent) (agentcontainers.SubAgent, error) {
+				assert.Equal(t, terraformAgentID, agent.ID, "agent should have terraform-defined ID")
+				agent.AuthToken = uuid.New()
+				return agent, nil
+			},
+		).Times(2)
+
+		// EXPECT: Delete may be called during Close, but not before.
+		mSAC.EXPECT().Delete(gomock.Any(), gomock.Any()).DoAndReturn(func(_ context.Context, _ uuid.UUID) error {
+			assert.True(t, closed, "Delete should only be called after Close, not during recreation")
+			return nil
+		}).AnyTimes()
+
+		api := agentcontainers.NewAPI(logger,
+			agentcontainers.WithContainerCLI(fCCLI),
+			agentcontainers.WithDevcontainerCLI(fDCCLI),
+			agentcontainers.WithDevcontainers(
+				[]codersdk.WorkspaceAgentDevcontainer{terraformDevcontainer},
+				[]codersdk.WorkspaceAgentScript{{ID: terraformDevcontainer.ID, LogSourceID: uuid.New()}},
+			),
+			agentcontainers.WithSubAgentClient(mSAC),
+			agentcontainers.WithSubAgentURL("test-subagent-url"),
+			agentcontainers.WithWatcher(watcher.NewNoop()),
+		)
+		api.Start()
+
+		// Given: We create the devcontainer for the first time.
+		err := api.CreateDevcontainer(terraformDevcontainer.WorkspaceFolder, terraformDevcontainer.ConfigPath)
+		require.NoError(t, err)
+
+		// When: The container is recreated (new container ID) with config changes.
+		terraformContainer.ID = "new-container-id"
+		fCCLI.containers.Containers = []codersdk.WorkspaceAgentContainer{terraformContainer}
+		fDCCLI.upID = terraformContainer.ID
+		fDCCLI.readConfig.MergedConfiguration.Customizations.Coder = []agentcontainers.CoderCustomization{{
+			Apps: []agentcontainers.SubAgentApp{{Slug: "app2"}}, // Changed app triggers recreation logic.
+		}}
+
+		err = api.CreateDevcontainer(terraformDevcontainer.WorkspaceFolder, terraformDevcontainer.ConfigPath, agentcontainers.WithRemoveExistingContainer())
+		require.NoError(t, err)
+
+		// Then: Mock expectations verify that Create was called once and Delete was not called during recreation.
+		closed = true
+		api.Close()
+	})
+
+	// Verify that rebuilding a terraform-defined devcontainer via the
+	// HTTP API does not delete the sub agent. The sub agent should be
+	// preserved (Create called again with the same terraform ID) and
+	// display app changes should be picked up.
+	t.Run("TerraformDefinedSubAgentRebuildViaHTTP", func(t *testing.T) {
+		t.Parallel()
+
+		if runtime.GOOS == "windows" {
+			t.Skip("Dev Container tests are not supported on Windows (this test uses mocks but fails due to Windows paths)")
+		}
+
+		var (
+			ctx    = testutil.Context(t, testutil.WaitMedium)
+			logger = slogtest.Make(t, &slogtest.Options{IgnoreErrors: true}).Leveled(slog.LevelDebug)
+			mCtrl  = gomock.NewController(t)
+
+			terraformAgentID = uuid.New()
+			containerID      = "test-container-id"
+
+			terraformContainer = codersdk.WorkspaceAgentContainer{
+				ID:           containerID,
+				FriendlyName: "test-container",
+				Image:        "test-image",
+				Running:      true,
+				CreatedAt:    time.Now(),
+				Labels: map[string]string{
+					agentcontainers.DevcontainerLocalFolderLabel: "/workspace/project",
+					agentcontainers.DevcontainerConfigFileLabel:  "/workspace/project/.devcontainer/devcontainer.json",
+				},
+			}
+			terraformDevcontainer = codersdk.WorkspaceAgentDevcontainer{
+				ID:              uuid.New(),
+				Name:            "terraform-devcontainer",
+				WorkspaceFolder: "/workspace/project",
+				ConfigPath:      "/workspace/project/.devcontainer/devcontainer.json",
+				SubagentID:      uuid.NullUUID{UUID: terraformAgentID, Valid: true},
+			}
+
+			fCCLI = &fakeContainerCLI{
+				containers: codersdk.WorkspaceAgentListContainersResponse{
+					Containers: []codersdk.WorkspaceAgentContainer{terraformContainer},
+				},
+				arch: runtime.GOARCH,
+			}
+
+			fDCCLI = &fakeDevcontainerCLI{
+				upID: containerID,
+				readConfig: agentcontainers.DevcontainerConfig{
+					MergedConfiguration: agentcontainers.DevcontainerMergedConfiguration{
+						Customizations: agentcontainers.DevcontainerMergedCustomizations{
+							Coder: []agentcontainers.CoderCustomization{{
+								DisplayApps: map[codersdk.DisplayApp]bool{
+									codersdk.DisplayAppSSH:         true,
+									codersdk.DisplayAppWebTerminal: true,
+								},
+							}},
+						},
+					},
+				},
+			}
+
+			mSAC   = acmock.NewMockSubAgentClient(mCtrl)
+			closed bool
+
+			createCalled = make(chan agentcontainers.SubAgent, 2)
+		)
+
+		mSAC.EXPECT().List(gomock.Any()).Return([]agentcontainers.SubAgent{}, nil).AnyTimes()
+
+		// Create should be called twice: once for the initial injection
+		// and once after the rebuild picks up the new container.
+		mSAC.EXPECT().Create(gomock.Any(), gomock.Any()).DoAndReturn(
+			func(_ context.Context, agent agentcontainers.SubAgent) (agentcontainers.SubAgent, error) {
+				assert.Equal(t, terraformAgentID, agent.ID, "agent should always use terraform-defined ID")
+				agent.AuthToken = uuid.New()
+				createCalled <- agent
+				return agent, nil
+			},
+		).Times(2)
+
+		// Delete must only be called during Close, never during rebuild.
+		mSAC.EXPECT().Delete(gomock.Any(), gomock.Any()).DoAndReturn(func(_ context.Context, _ uuid.UUID) error {
+			assert.True(t, closed, "Delete should only be called after Close, not during rebuild")
+			return nil
+		}).AnyTimes()
+
+		api := agentcontainers.NewAPI(logger,
+			agentcontainers.WithContainerCLI(fCCLI),
+			agentcontainers.WithDevcontainerCLI(fDCCLI),
+			agentcontainers.WithDevcontainers(
+				[]codersdk.WorkspaceAgentDevcontainer{terraformDevcontainer},
+				[]codersdk.WorkspaceAgentScript{{ID: terraformDevcontainer.ID, LogSourceID: uuid.New()}},
+			),
+			agentcontainers.WithSubAgentClient(mSAC),
+			agentcontainers.WithSubAgentURL("test-subagent-url"),
+			agentcontainers.WithWatcher(watcher.NewNoop()),
+		)
+		api.Start()
+		defer func() {
+			closed = true
+			api.Close()
+		}()
+
+		r := chi.NewRouter()
+		r.Mount("/", api.Routes())
+
+		// Perform the initial devcontainer creation directly to set up
+		// the subagent (mirrors the TerraformDefinedSubAgentNotRecreatedOnConfigChange
+		// test pattern).
+		err := api.CreateDevcontainer(terraformDevcontainer.WorkspaceFolder, terraformDevcontainer.ConfigPath)
+		require.NoError(t, err)
+
+		initialAgent := testutil.RequireReceive(ctx, t, createCalled)
+		assert.Equal(t, terraformAgentID, initialAgent.ID)
+
+		// Simulate container rebuild: new container ID, changed display apps.
+		newContainerID := "new-container-id"
+		terraformContainer.ID = newContainerID
+		fCCLI.containers.Containers = []codersdk.WorkspaceAgentContainer{terraformContainer}
+		fDCCLI.upID = newContainerID
+		fDCCLI.readConfig.MergedConfiguration.Customizations.Coder = []agentcontainers.CoderCustomization{{
+			DisplayApps: map[codersdk.DisplayApp]bool{
+				codersdk.DisplayAppSSH:            true,
+				codersdk.DisplayAppWebTerminal:    true,
+				codersdk.DisplayAppVSCodeDesktop:  true,
+				codersdk.DisplayAppVSCodeInsiders: true,
+			},
+		}}
+
+		// Issue the rebuild request via the HTTP API.
+		req := httptest.NewRequest(http.MethodPost, "/devcontainers/"+terraformDevcontainer.ID.String()+"/recreate", nil).
+			WithContext(ctx)
+		rec := httptest.NewRecorder()
+		r.ServeHTTP(rec, req)
+		require.Equal(t, http.StatusAccepted, rec.Code)
+
+		// Wait for the post-rebuild injection to complete.
+		rebuiltAgent := testutil.RequireReceive(ctx, t, createCalled)
+		assert.Equal(t, terraformAgentID, rebuiltAgent.ID, "rebuilt agent should preserve terraform ID")
+
+		// Verify that the display apps were updated.
+		assert.Contains(t, rebuiltAgent.DisplayApps, codersdk.DisplayAppVSCodeDesktop,
+			"rebuilt agent should include updated display apps")
+		assert.Contains(t, rebuiltAgent.DisplayApps, codersdk.DisplayAppVSCodeInsiders,
+			"rebuilt agent should include updated display apps")
+	})
+
 	t.Run("Error", func(t *testing.T) {
 		t.Parallel()
 

agent/agentcontainers/subagent.go

@@ -24,10 +24,12 @@ type SubAgent struct {
 	DisplayApps     []codersdk.DisplayApp
 }
 
-// CloneConfig makes a copy of SubAgent without ID and AuthToken. The
-// name is inherited from the devcontainer.
+// CloneConfig makes a copy of SubAgent using configuration from the
+// devcontainer. The ID is inherited from dc.SubagentID if present, and
+// the name is inherited from the devcontainer. AuthToken is not copied.
 func (s SubAgent) CloneConfig(dc codersdk.WorkspaceAgentDevcontainer) SubAgent {
 	return SubAgent{
+		ID:              dc.SubagentID.UUID,
 		Name:            dc.Name,
 		Directory:       s.Directory,
 		Architecture:    s.Architecture,
@@ -190,6 +192,11 @@ func (a *subAgentAPIClient) List(ctx context.Context) ([]SubAgent, error) {
 func (a *subAgentAPIClient) Create(ctx context.Context, agent SubAgent) (_ SubAgent, err error) {
 	a.logger.Debug(ctx, "creating sub agent", slog.F("name", agent.Name), slog.F("directory", agent.Directory))
 
+	var id []byte
+	if agent.ID != uuid.Nil {
+		id = agent.ID[:]
+	}
+
 	displayApps := make([]agentproto.CreateSubAgentRequest_DisplayApp, 0, len(agent.DisplayApps))
 	for _, displayApp := range agent.DisplayApps {
 		var app agentproto.CreateSubAgentRequest_DisplayApp
@@ -228,6 +235,7 @@ func (a *subAgentAPIClient) Create(ctx context.Context, agent SubAgent) (_ SubAg
 		OperatingSystem: agent.OperatingSystem,
 		DisplayApps:     displayApps,
 		Apps:            apps,
+		Id:              id,
 	})
 	if err != nil {
 		return SubAgent{}, err

agent/agentcontainers/subagent_test.go

@@ -306,3 +306,128 @@ func TestSubAgentClient_CreateWithDisplayApps(t *testing.T) {
 		}
 	})
 }
+
+func TestSubAgent_CloneConfig(t *testing.T) {
+	t.Parallel()
+
+	t.Run("CopiesIDFromDevcontainer", func(t *testing.T) {
+		t.Parallel()
+
+		subAgent := agentcontainers.SubAgent{
+			ID:              uuid.New(),
+			Name:            "original-name",
+			Directory:       "/workspace",
+			Architecture:    "amd64",
+			OperatingSystem: "linux",
+			DisplayApps:     []codersdk.DisplayApp{codersdk.DisplayAppVSCodeDesktop},
+			Apps:            []agentcontainers.SubAgentApp{{Slug: "app1"}},
+		}
+		expectedID := uuid.MustParse("550e8400-e29b-41d4-a716-446655440000")
+		dc := codersdk.WorkspaceAgentDevcontainer{
+			Name:       "devcontainer-name",
+			SubagentID: uuid.NullUUID{UUID: expectedID, Valid: true},
+		}
+
+		cloned := subAgent.CloneConfig(dc)
+
+		assert.Equal(t, expectedID, cloned.ID)
+		assert.Equal(t, dc.Name, cloned.Name)
+		assert.Equal(t, subAgent.Directory, cloned.Directory)
+		assert.Zero(t, cloned.AuthToken, "AuthToken should not be copied")
+	})
+
+	t.Run("HandlesNilSubagentID", func(t *testing.T) {
+		t.Parallel()
+
+		subAgent := agentcontainers.SubAgent{
+			ID:              uuid.New(),
+			Name:            "original-name",
+			Directory:       "/workspace",
+			Architecture:    "amd64",
+			OperatingSystem: "linux",
+		}
+		dc := codersdk.WorkspaceAgentDevcontainer{
+			Name:       "devcontainer-name",
+			SubagentID: uuid.NullUUID{Valid: false},
+		}
+
+		cloned := subAgent.CloneConfig(dc)
+
+		assert.Equal(t, uuid.Nil, cloned.ID)
+	})
+}
+
+func TestSubAgent_EqualConfig(t *testing.T) {
+	t.Parallel()
+
+	base := agentcontainers.SubAgent{
+		ID:              uuid.New(),
+		Name:            "test-agent",
+		Directory:       "/workspace",
+		Architecture:    "amd64",
+		OperatingSystem: "linux",
+		DisplayApps:     []codersdk.DisplayApp{codersdk.DisplayAppVSCodeDesktop},
+		Apps: []agentcontainers.SubAgentApp{
+			{Slug: "test-app", DisplayName: "Test App"},
+		},
+	}
+
+	tests := []struct {
+		name      string
+		modify    func(*agentcontainers.SubAgent)
+		wantEqual bool
+	}{
+		{
+			name:      "identical",
+			modify:    func(s *agentcontainers.SubAgent) {},
+			wantEqual: true,
+		},
+		{
+			name:      "different ID",
+			modify:    func(s *agentcontainers.SubAgent) { s.ID = uuid.New() },
+			wantEqual: true,
+		},
+		{
+			name:      "different Name",
+			modify:    func(s *agentcontainers.SubAgent) { s.Name = "different-name" },
+			wantEqual: false,
+		},
+		{
+			name:      "different Directory",
+			modify:    func(s *agentcontainers.SubAgent) { s.Directory = "/different/path" },
+			wantEqual: false,
+		},
+		{
+			name:      "different Architecture",
+			modify:    func(s *agentcontainers.SubAgent) { s.Architecture = "arm64" },
+			wantEqual: false,
+		},
+		{
+			name:      "different OperatingSystem",
+			modify:    func(s *agentcontainers.SubAgent) { s.OperatingSystem = "windows" },
+			wantEqual: false,
+		},
+		{
+			name:      "different DisplayApps",
+			modify:    func(s *agentcontainers.SubAgent) { s.DisplayApps = []codersdk.DisplayApp{codersdk.DisplayAppSSH} },
+			wantEqual: false,
+		},
+		{
+			name: "different Apps",
+			modify: func(s *agentcontainers.SubAgent) {
+				s.Apps = []agentcontainers.SubAgentApp{{Slug: "different-app", DisplayName: "Different App"}}
+			},
+			wantEqual: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			modified := base
+			tt.modify(&modified)
+			assert.Equal(t, tt.wantEqual, base.EqualConfig(modified))
+		})
+	}
+}