fix(backend): honor base_branch for same-repo subtasks via MCP (kdlbs#1093)

* fix(backend): forward base_branch override for same-repo subtasks via MCP

The create_task_kandev MCP handler dropped base_branch silently unless
the caller also passed a repository identifier. Same-repo subtasks then
inherited the parent's repos verbatim, so "branch off feature/X" calls
landed on the parent's branch instead.

Forward base_branch at the top level of the WS payload and apply it as
an override on the resolved repo list when no per-repo entries were
supplied; explicit per-repo BaseBranch wins as before.

* docs(backend): correct BaseBranch field comment to match actual fallback semantics

The struct doc on `req.BaseBranch` claimed it won over explicit per-repo
entries, but the override only fires when `len(req.Repositories) == 0`.
Reword as a fallback applied to inherited/resolved repos when no
per-repo list is supplied; explicit per-repo BaseBranch stays
authoritative when set. Flagged by CodeRabbit and Greptile.

* refactor(backend): forward top-level base_branch only when no per-repo entries

When the MCP caller supplies a repo identifier, the per-repo base_branch
is already authoritative on the backend side, so emitting a top-level
base_branch in the same payload was dead weight that the backend's
override gate explicitly ignored. Move the top-level forward into the
else of hasRepo so the two paths are mutually exclusive and the wire
contract reads as "top-level base_branch means inherit-with-override".
Flagged by the Claude review bot.

Author: zeval

apps/backend/internal/mcp/handlers/handlers.go

@@ -366,6 +366,7 @@ func (h *Handlers) handleCreateTask(ctx context.Context, msg *ws.Message) (*ws.M
 		ExecutorProfileID      string               `json:"executor_profile_id"`
 		StartAgent             *bool                `json:"start_agent"`               // nil means default to true for backward compatibility
 		Repositories           []mcpRepositoryInput `json:"repositories"`              // explicit repositories for top-level tasks
+		BaseBranch             string               `json:"base_branch"`               // top-level fallback applied to every resolved repo only when no per-repo entries are supplied; explicit per-repo BaseBranch is authoritative when Repositories is set
 		BlockedBy              []string             `json:"blocked_by"`                // task IDs that must complete before this task
 		AssigneeAgentProfileID string               `json:"assignee_agent_profile_id"` // agent instance to assign the task to
 		// Office task-handoffs phase 4 — workspace policy.
@@ -395,6 +396,17 @@ func (h *Handlers) handleCreateTask(ctx context.Context, msg *ws.Message) (*ws.M
 		return ws.NewError(msg.ID, msg.Action, ws.ErrorCodeValidation, err.Error(), nil)
 	}
 	repos := resolved.Repos
+	// Top-level base_branch override: when the caller passes base_branch
+	// without any per-repo entries, apply it to every repo in the resolved
+	// list. This is the only path that lets a same-repo subtask override
+	// the parent's inherited base_branch without also restating the
+	// repository identifier. When the caller provided explicit per-repo
+	// entries we leave their BaseBranch alone — those are authoritative.
+	if req.BaseBranch != "" && len(req.Repositories) == 0 {
+		for i := range repos {
+			repos[i].BaseBranch = req.BaseBranch
+		}
+	}
 	if req.WorkspaceID == "" {
 		req.WorkspaceID = resolved.WorkspaceID
 	}

apps/backend/internal/mcp/handlers/handlers_test.go

@@ -380,6 +380,94 @@ func TestCreateSubtaskFromParent_DifferentRepoUsesNewRepoDefault(t *testing.T) {
 	assert.Equal(t, "trunk", subtask.Repositories[0].BaseBranch, "cross-repo subtask should anchor to the new repo's default_branch, not parent's pr-metrics")
 }
 
+// TestHandleCreateTask_SubtaskBaseBranchOverride pins the bug-fix path:
+// when an MCP caller passes base_branch at the top level (no per-repo
+// entries) for a same-repo subtask, the override beats the parent's
+// inherited base_branch. Previously the top-level base_branch was
+// silently dropped unless the caller also restated repository_id, so a
+// "give me a child task that branches off feature/X" call quietly
+// landed on the parent's branch instead.
+func TestHandleCreateTask_SubtaskBaseBranchOverride(t *testing.T) {
+	svc, repo := newTestTaskService(t)
+	ctx := context.Background()
+	parentID := seedParentWithRepo(t, svc, repo)
+
+	log := testLogger(t)
+	h := &Handlers{taskSvc: svc, logger: log.WithFields()}
+
+	msg := makeWSMessage(t, ws.ActionMCPCreateTask, map[string]interface{}{
+		"title":       "Child",
+		"description": "do the thing",
+		"parent_id":   parentID,
+		"base_branch": "feature/create-new-page-endp-05z",
+		"start_agent": false,
+	})
+
+	resp, err := h.handleCreateTask(ctx, msg)
+	require.NoError(t, err)
+	require.Equalf(t, ws.MessageTypeResponse, resp.Type, "create_task should succeed; payload: %s", string(resp.Payload))
+
+	var created struct {
+		ID string `json:"id"`
+	}
+	require.NoError(t, json.Unmarshal(resp.Payload, &created))
+	require.NotEmpty(t, created.ID)
+
+	subtask, err := svc.GetTask(ctx, created.ID)
+	require.NoError(t, err)
+	require.Len(t, subtask.Repositories, 1, "subtask should inherit parent's repository")
+	assert.Equal(t, "repo-parent", subtask.Repositories[0].RepositoryID, "subtask should still bind to parent's repo")
+	assert.Equal(t, "feature/create-new-page-endp-05z", subtask.Repositories[0].BaseBranch,
+		"top-level base_branch must override parent's inherited base_branch when no explicit repos are passed")
+}
+
+// TestHandleCreateTask_SubtaskBaseBranchOverride_ExplicitReposWin asserts
+// the inverse: when the caller provides per-repo entries, those are
+// authoritative — the top-level base_branch must NOT clobber an explicit
+// per-repo BaseBranch. This preserves cross-repo and multi-repo callers
+// that already control branch selection per entry.
+func TestHandleCreateTask_SubtaskBaseBranchOverride_ExplicitReposWin(t *testing.T) {
+	svc, repo := newTestTaskService(t)
+	ctx := context.Background()
+	parentID := seedParentWithRepo(t, svc, repo)
+
+	require.NoError(t, repo.CreateRepository(ctx, &models.Repository{
+		ID: "repo-sibling", WorkspaceID: "ws-1", Name: "Sibling", DefaultBranch: "trunk",
+	}))
+
+	log := testLogger(t)
+	h := &Handlers{taskSvc: svc, logger: log.WithFields()}
+
+	msg := makeWSMessage(t, ws.ActionMCPCreateTask, map[string]interface{}{
+		"title":       "Cross-repo child",
+		"description": "do the thing",
+		"parent_id":   parentID,
+		// Explicit per-repo entry with its own base_branch.
+		"repositories": []map[string]interface{}{
+			{"repository_id": "repo-sibling", "base_branch": "develop"},
+		},
+		// Top-level base_branch should be ignored because explicit repos win.
+		"base_branch": "should-not-be-applied",
+		"start_agent": false,
+	})
+
+	resp, err := h.handleCreateTask(ctx, msg)
+	require.NoError(t, err)
+	require.Equalf(t, ws.MessageTypeResponse, resp.Type, "create_task should succeed; payload: %s", string(resp.Payload))
+
+	var created struct {
+		ID string `json:"id"`
+	}
+	require.NoError(t, json.Unmarshal(resp.Payload, &created))
+
+	subtask, err := svc.GetTask(ctx, created.ID)
+	require.NoError(t, err)
+	require.Len(t, subtask.Repositories, 1)
+	assert.Equal(t, "repo-sibling", subtask.Repositories[0].RepositoryID)
+	assert.Equal(t, "develop", subtask.Repositories[0].BaseBranch,
+		"explicit per-repo base_branch must win over the top-level override")
+}
+
 func TestResolveTaskRepositories_ParentWithExplicitRepos_OverridesRepoButInheritsWorkspace(t *testing.T) {
 	svc, repo := newTestTaskService(t)
 	parentID := seedParentWithRepo(t, svc, repo)

apps/backend/internal/mcp/server/handlers.go

@@ -184,6 +184,13 @@ func (s *Server) createTaskHandler() server.ToolHandlerFunc {
 				repo["base_branch"] = baseBranch
 			}
 			payload["repositories"] = []map[string]string{repo}
+		} else if baseBranch != "" {
+			// Forward base_branch at the top level only when the caller
+			// supplied no repo identifier — the backend uses it as a fallback
+			// applied to inherited subtask repos. When explicit repo entries
+			// are present, the per-repo base_branch above is authoritative
+			// and a top-level value here would be ignored.
+			payload["base_branch"] = baseBranch
 		}
 
 		var result map[string]interface{}

apps/backend/internal/mcp/server/handlers_test.go

@@ -252,6 +252,35 @@ func TestCreateTask_WithRepositoryURL(t *testing.T) {
 	assert.Equal(t, "main", repos[0]["base_branch"])
 }
 
+// TestCreateTask_BaseBranchOnly_ForwardsTopLevel pins the bug-fix wiring:
+// when the caller passes only base_branch (no repository_id / local_path /
+// repository_url), the MCP server forwards it at the top level of the WS
+// payload so the backend can apply it as an override on inherited
+// subtask repos. Previously base_branch was silently dropped when no
+// repo identifier was passed.
+func TestCreateTask_BaseBranchOnly_ForwardsTopLevel(t *testing.T) {
+	backend := &testBackend{
+		response: map[string]interface{}{"id": "subtask-1", "parent_id": "task-current"},
+	}
+	s := newTaskModeServer(t, backend, "task-current")
+
+	result := callTool(t, s, "create_task_kandev", map[string]interface{}{
+		"title":       "Stacked PR child",
+		"parent_id":   "self",
+		"description": "branch off the parent's PR branch",
+		"base_branch": "feature/create-new-page-endp-05z",
+	})
+
+	assert.False(t, result.IsError)
+
+	payload, ok := backend.lastPayload.(map[string]interface{})
+	require.True(t, ok)
+	assert.Equal(t, "feature/create-new-page-endp-05z", payload["base_branch"],
+		"base_branch should be forwarded at the top level even when no repo identifier is supplied")
+	_, hasRepos := payload["repositories"]
+	assert.False(t, hasRepos, "no repositories slice should be produced when only base_branch is supplied")
+}
+
 func TestCreateTask_RepositoryURL_AllowedForSubtasks(t *testing.T) {
 	backend := &testBackend{
 		response: map[string]interface{}{"id": "task-new", "title": "Subtask with URL"},