fix(mcp): recover ambiguous project writes

Author: Alan-TheGentleman

docs/AGENT-SETUP.md

@@ -27,7 +27,7 @@ Engram works with **any MCP-compatible agent**. Pick your agent below.
 
 ### Project auto-detection (important)
 
-**Do not pass `project` to write tools.** Engram auto-detects the project from the server's working directory (cwd) using `.engram/config.json`, git remote URL, repo root name, or directory basename. Agents that include `project` in `mem_save` or similar calls will have that argument silently discarded.
+**Do not pass `project` to write tools during normal operation.** Engram auto-detects the project from the server's working directory (cwd) using `.engram/config.json`, git remote URL, repo root name, or directory basename. Agents that include `project` in `mem_save` or similar calls will have that argument ignored unless they are using the explicit ambiguous-project recovery flow below.
 
 To lock write tools to the canonical project for a repo, add `.engram/config.json` at the repo root:
 
@@ -41,6 +41,17 @@ When present, `project_name` is used for writes from the repo and its subdirecto
 
 **Recommended first call:** `mem_current_project` — confirms which project Engram detected before you start writing. Returns `project_source` (how it was detected) and `available_projects` (if cwd is ambiguous).
 
+If a write tool returns `ambiguous_project`, the agent must not guess. Ask the user to choose one of `available_projects`, then retry only `mem_save` or `mem_save_prompt` with both fields:
+
+```json
+{
+  "project": "chosen-project-from-available-projects",
+  "project_choice_reason": "user_selected_after_ambiguous_project"
+}
+```
+
+This recovery path is accepted only after cwd detection is ambiguous and only when `project` exactly matches one of the reported `available_projects`. In all non-ambiguous cases, `.engram/config.json`/git/cwd detection remains authoritative and the explicit `project` is ignored. Alternatives: `cd` into the target repo before starting the MCP server, or add repo `.engram/config.json`.
+
 **Read tools** (`mem_search`, `mem_context`, `mem_get_observation`, `mem_stats`, `mem_timeline`) accept an optional `project` override validated against the store. Omit it to auto-detect.
 
 ---

internal/mcp/mcp.go

@@ -328,6 +328,12 @@ Examples:
 				mcp.WithString("topic_key",
 					mcp.Description("Optional topic identifier for upserts (e.g. architecture/auth-model). Reuses and updates the latest observation in same project+scope."),
 				),
+				mcp.WithString("project",
+					mcp.Description("Optional recovery target only after ambiguous_project. Ignored unless project_choice_reason is user_selected_after_ambiguous_project."),
+				),
+				mcp.WithString("project_choice_reason",
+					mcp.Description("Must be user_selected_after_ambiguous_project, and only after the user explicitly chose one of available_projects from an ambiguous_project error."),
+				),
 			),
 			queuedWriteHandler(writeQueue, handleSave(s, cfg, activity)),
 		)
@@ -433,6 +439,12 @@ Examples:
 				mcp.WithString("session_id",
 					mcp.Description("Session ID to associate with (default: manual-save-{project})"),
 				),
+				mcp.WithString("project",
+					mcp.Description("Optional recovery target only after ambiguous_project. Ignored unless project_choice_reason is user_selected_after_ambiguous_project."),
+				),
+				mcp.WithString("project_choice_reason",
+					mcp.Description("Must be user_selected_after_ambiguous_project, and only after the user explicitly chose one of available_projects from an ambiguous_project error."),
+				),
 			),
 			queuedWriteHandler(writeQueue, handleSavePrompt(s, cfg)),
 		)
@@ -996,10 +1008,12 @@ func handleSave(s *store.Store, cfg MCPConfig, activity *SessionActivity) server
 		sessionID, _ := req.GetArguments()["session_id"].(string)
 		scope, _ := req.GetArguments()["scope"].(string)
 		topicKey, _ := req.GetArguments()["topic_key"].(string)
-		// project field intentionally not read — auto-detect only (REQ-308)
+		projectChoice, _ := req.GetArguments()["project"].(string)
+		projectChoiceReason, _ := req.GetArguments()["project_choice_reason"].(string)
 
-		// Auto-detect project from cwd; fail fast on ambiguous (REQ-308, REQ-309)
-		detRes, err := resolveWriteProject()
+		// Auto-detect project from cwd; only allow explicit user-selected recovery
+		// after ErrAmbiguousProject (issue #306).
+		detRes, err := resolveWriteProjectWithChoice(projectChoice, projectChoiceReason)
 		if err != nil {
 			return writeProjectErrorResult(detRes, err), nil
 		}
@@ -1232,9 +1246,10 @@ func handleSavePrompt(s *store.Store, cfg MCPConfig) server.ToolHandlerFunc {
 	return func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 		content, _ := req.GetArguments()["content"].(string)
 		sessionID, _ := req.GetArguments()["session_id"].(string)
-		// project field intentionally not read — auto-detect only (REQ-308)
+		projectChoice, _ := req.GetArguments()["project"].(string)
+		projectChoiceReason, _ := req.GetArguments()["project_choice_reason"].(string)
 
-		detRes, err := resolveWriteProject()
+		detRes, err := resolveWriteProjectWithChoice(projectChoice, projectChoiceReason)
 		if err != nil {
 			return writeProjectErrorResult(detRes, err), nil
 		}
@@ -1866,6 +1881,15 @@ func (e *unknownProjectError) Error() string {
 	return "unknown project: " + e.Name
 }
 
+type invalidProjectChoiceError struct {
+	Name              string
+	AvailableProjects []string
+}
+
+func (e *invalidProjectChoiceError) Error() string {
+	return "invalid project choice: " + e.Name
+}
+
 // resolveWriteProject detects the current project from the process working
 // directory. Returns ErrAmbiguousProject if cwd is a parent of multiple repos.
 func resolveWriteProject() (projectpkg.DetectionResult, error) {
@@ -1880,6 +1904,47 @@ func resolveWriteProject() (projectpkg.DetectionResult, error) {
 	return res, nil
 }
 
+// resolveWriteProjectWithChoice preserves normal write resolution authority and
+// only uses an explicit project choice as a recovery path from ErrAmbiguousProject.
+func resolveWriteProjectWithChoice(projectChoice, reason string) (projectpkg.DetectionResult, error) {
+	res, err := resolveWriteProject()
+	if err == nil {
+		// Non-ambiguous config/git/autodetect remains authoritative. Ignore any
+		// supplied project choice so agents cannot drift writes to arbitrary buckets.
+		return res, nil
+	}
+	if !errors.Is(err, projectpkg.ErrAmbiguousProject) {
+		return res, err
+	}
+
+	if strings.TrimSpace(reason) != projectpkg.SourceUserSelectedAfterAmbiguousProject {
+		return res, err
+	}
+
+	choice, _ := store.NormalizeProject(projectChoice)
+	if choice == "" || !containsProjectChoice(res.AvailableProjects, choice) {
+		return res, &invalidProjectChoiceError{
+			Name:              choice,
+			AvailableProjects: res.AvailableProjects,
+		}
+	}
+
+	res.Project = choice
+	res.Source = projectpkg.SourceUserSelectedAfterAmbiguousProject
+	res.Warning = "project selected by user after ambiguous_project recovery"
+	return res, nil
+}
+
+func containsProjectChoice(available []string, choice string) bool {
+	for _, candidate := range available {
+		normalized, _ := store.NormalizeProject(candidate)
+		if normalized == choice {
+			return true
+		}
+	}
+	return false
+}
+
 // resolveReadProject validates an optional project override against the store.
 // If override is empty, falls back to auto-detection from cwd.
 // JW2: normalizes the override (lowercase+trim) before ProjectExists lookup so
@@ -1934,6 +1999,13 @@ func writeProjectErrorResult(res projectpkg.DetectionResult, err error) *mcp.Cal
 	if errors.Is(err, projectpkg.ErrInvalidConfig) {
 		code = "invalid_project_config"
 	}
+	var choiceErr *invalidProjectChoiceError
+	if errors.As(err, &choiceErr) {
+		return errorWithMeta("invalid_project_choice",
+			fmt.Sprintf("Project choice %q is not one of available_projects", choiceErr.Name),
+			choiceErr.AvailableProjects,
+		)
+	}
 	return errorWithMeta(code, fmt.Sprintf("Cannot determine project: %s", err), res.AvailableProjects)
 }
 
@@ -1947,7 +2019,9 @@ func errorWithMeta(code, msg string, availableProjects []string) *mcp.CallToolRe
 	}
 	switch code {
 	case "ambiguous_project":
-		envelope["hint"] = "Use mem_current_project to inspect detection results, or cd into one of the listed repositories."
+		envelope["hint"] = "Ask the user to choose one of available_projects, then retry mem_save or mem_save_prompt with project and project_choice_reason=user_selected_after_ambiguous_project; alternatively cd into the target repo or add repo .engram/config.json."
+	case "invalid_project_choice":
+		envelope["hint"] = "Use exactly one of available_projects after asking the user, or cd into the target repo, or add repo .engram/config.json."
 	case "unknown_project":
 		envelope["hint"] = "Use one of the available_projects values, or omit project to auto-detect."
 	case "invalid_project_config":

internal/mcp/mcp_test.go

@@ -2789,12 +2789,16 @@ func TestSessionStartWithExplicitDirectoryResolvesProjectFromDirectory(t *testin
 
 // ─── Batch 4: Write handler schema + auto-detect ─────────────────────────────
 
-// TestWriteSchema_NoProjectField asserts that the 6 write tools do NOT include
-// a "project" property in their input schema (REQ-308).
+// TestWriteSchema_ProjectFieldOnlyForAmbiguousRecovery asserts that only the
+// write tools with explicit ambiguous-project recovery expose project fields.
 func TestWriteSchema_NoProjectField(t *testing.T) {
 	s := newMCPTestStore(t)
 	srv := NewServer(s)
 
+	recoveryTools := map[string]bool{
+		"mem_save":        true,
+		"mem_save_prompt": true,
+	}
 	writeTools := []string{
 		"mem_save",
 		"mem_save_prompt",
@@ -2811,6 +2815,15 @@ func TestWriteSchema_NoProjectField(t *testing.T) {
 				t.Fatalf("tool %q not registered", toolName)
 			}
 			props := st.Tool.InputSchema.Properties
+			if recoveryTools[toolName] {
+				if _, hasProject := props["project"]; !hasProject {
+					t.Errorf("tool %q must expose 'project' for ambiguous-project recovery", toolName)
+				}
+				if _, hasReason := props["project_choice_reason"]; !hasReason {
+					t.Errorf("tool %q must expose 'project_choice_reason' for ambiguous-project recovery", toolName)
+				}
+				return
+			}
 			if _, hasProject := props["project"]; hasProject {
 				t.Errorf("tool %q must not have 'project' in schema", toolName)
 			}
@@ -2931,6 +2944,145 @@ func TestMemSave_AmbiguousEnvelope(t *testing.T) {
 	if !strings.Contains(text, "available_projects") {
 		t.Errorf("expected available_projects in error, got: %q", text)
 	}
+	if !strings.Contains(text, "project_choice_reason=user_selected_after_ambiguous_project") {
+		t.Errorf("expected explicit recovery hint, got: %q", text)
+	}
+}
+
+func TestMemSave_AmbiguousWithValidUserChoiceSucceeds(t *testing.T) {
+	parent := t.TempDir()
+	for _, name := range []string{"repo-choice-a", "repo-choice-b"} {
+		child := filepath.Join(parent, name)
+		if err := os.MkdirAll(child, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		initTestGitRepo(t, child)
+	}
+	t.Chdir(parent)
+
+	s := newMCPTestStore(t)
+	h := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":                 "chosen project memory",
+		"content":               "saved after explicit user choice",
+		"type":                  "manual",
+		"project":               "repo-choice-b",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil || res.IsError {
+		t.Fatalf("mem_save with choice failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
+	}
+	body := callResultJSON(t, res)
+	if body["project"] != "repo-choice-b" || body["project_source"] != project.SourceUserSelectedAfterAmbiguousProject {
+		t.Fatalf("expected explicit user choice envelope, got %v", body)
+	}
+	obs, err := s.Search("chosen project memory", store.SearchOptions{Project: "repo-choice-b", Limit: 5})
+	if err != nil || len(obs) != 1 {
+		t.Fatalf("expected observation in selected project, obs=%d err=%v", len(obs), err)
+	}
+}
+
+func TestMemSave_AmbiguousWithInventedProjectRejected(t *testing.T) {
+	parent := t.TempDir()
+	for _, name := range []string{"repo-valid-a", "repo-valid-b"} {
+		child := filepath.Join(parent, name)
+		if err := os.MkdirAll(child, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		initTestGitRepo(t, child)
+	}
+	t.Chdir(parent)
+
+	s := newMCPTestStore(t)
+	h := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"title":                 "invented project memory",
+		"content":               "must not save",
+		"project":               "invented-project",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if !res.IsError {
+		t.Fatal("expected invalid project choice error")
+	}
+	body := callResultJSON(t, res)
+	if body["error_code"] != "invalid_project_choice" {
+		t.Fatalf("expected invalid_project_choice, got %v", body)
+	}
+	if strings.Contains(callResultText(t, res), "invented-project\",\"available_projects") {
+		t.Fatalf("invented project must not be treated as available: %q", callResultText(t, res))
+	}
+	obs, err := s.Search("invented project memory", store.SearchOptions{Project: "invented-project", Limit: 5})
+	if err != nil || len(obs) != 0 {
+		t.Fatalf("invented project must not receive writes, obs=%d err=%v", len(obs), err)
+	}
+}
+
+func TestMemSavePrompt_AmbiguousWithValidUserChoiceSucceeds(t *testing.T) {
+	parent := t.TempDir()
+	for _, name := range []string{"repo-prompt-a", "repo-prompt-b"} {
+		child := filepath.Join(parent, name)
+		if err := os.MkdirAll(child, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		initTestGitRepo(t, child)
+	}
+	t.Chdir(parent)
+
+	s := newMCPTestStore(t)
+	h := handleSavePrompt(s, MCPConfig{})
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"content":               "prompt after user chose repo-prompt-a",
+		"project":               "repo-prompt-a",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil || res.IsError {
+		t.Fatalf("mem_save_prompt with choice failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
+	}
+	body := callResultJSON(t, res)
+	if body["project"] != "repo-prompt-a" || body["project_source"] != project.SourceUserSelectedAfterAmbiguousProject {
+		t.Fatalf("expected explicit user choice envelope, got %v", body)
+	}
+	prompts, err := s.RecentPrompts("repo-prompt-a", 5)
+	if err != nil || len(prompts) != 1 {
+		t.Fatalf("expected prompt in selected project, prompts=%d err=%v", len(prompts), err)
+	}
+}
+
+func TestMemSavePrompt_AmbiguousWithInventedProjectRejected(t *testing.T) {
+	parent := t.TempDir()
+	for _, name := range []string{"repo-prompt-valid-a", "repo-prompt-valid-b"} {
+		child := filepath.Join(parent, name)
+		if err := os.MkdirAll(child, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		initTestGitRepo(t, child)
+	}
+	t.Chdir(parent)
+
+	s := newMCPTestStore(t)
+	h := handleSavePrompt(s, MCPConfig{})
+	res, err := h(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
+		"content":               "prompt must not save",
+		"project":               "invented-prompt-project",
+		"project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
+	}}})
+	if err != nil {
+		t.Fatalf("handler error: %v", err)
+	}
+	if !res.IsError {
+		t.Fatal("expected invalid project choice error")
+	}
+	body := callResultJSON(t, res)
+	if body["error_code"] != "invalid_project_choice" {
+		t.Fatalf("expected invalid_project_choice, got %v", body)
+	}
+	prompts, err := s.RecentPrompts("invented-prompt-project", 5)
+	if err != nil || len(prompts) != 0 {
+		t.Fatalf("invented project must not receive prompt, prompts=%d err=%v", len(prompts), err)
+	}
 }
 
 // TestMemSave_SuccessEnvelope asserts project, project_source, project_path in response (REQ-309).
@@ -3348,6 +3500,7 @@ func TestHandleSaveAndPromptUseConfigProjectForWrites(t *testing.T) {
 	save := handleSave(s, MCPConfig{}, NewSessionActivity(10*time.Minute))
 	res, err := save(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
 		"title": "config write", "content": "memory saved under config project", "type": "decision",
+		"project": "attempted-override", "project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
 	}}})
 	if err != nil || res.IsError {
 		t.Fatalf("mem_save failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
@@ -3360,6 +3513,7 @@ func TestHandleSaveAndPromptUseConfigProjectForWrites(t *testing.T) {
 	prompt := handleSavePrompt(s, MCPConfig{})
 	res, err = prompt(context.Background(), mcppkg.CallToolRequest{Params: mcppkg.CallToolParams{Arguments: map[string]any{
 		"content": "prompt saved under config project",
+		"project": "attempted-override", "project_choice_reason": project.SourceUserSelectedAfterAmbiguousProject,
 	}}})
 	if err != nil || res.IsError {
 		t.Fatalf("mem_save_prompt failed: err=%v isError=%v text=%q", err, res.IsError, callResultText(t, res))
@@ -3377,6 +3531,9 @@ func TestHandleSaveAndPromptUseConfigProjectForWrites(t *testing.T) {
 	if err != nil || len(prompts) != 1 {
 		t.Fatalf("expected prompt written to config project, prompts=%d err=%v", len(prompts), err)
 	}
+	if wrong, _ := s.Search("memory saved under config project", store.SearchOptions{Project: "attempted-override", Limit: 5}); len(wrong) != 0 {
+		t.Fatal("explicit project choice must not override non-ambiguous/config project")
+	}
 }
 
 // TestResolveWriteProject_AmbiguousError: assert errors.Is(err, ErrAmbiguousProject)

internal/project/detect.go

@@ -33,8 +33,12 @@ const (
 	SourceDirBasename      = "dir_basename"      // fallback: directory basename
 	SourceAmbiguous        = "ambiguous"         // cwd contains multiple git repos (Case 4)
 	SourceExplicitOverride = "explicit_override" // JR2-2: caller explicitly supplied a project name
-	SourceRequestBody      = "request_body"      // REQ-414: project came from the request body (server-side, no filesystem path)
-	SourceConfig           = "config"            // derived from .engram/config.json project_name
+	// SourceUserSelectedAfterAmbiguousProject means an MCP write initially hit
+	// ErrAmbiguousProject and the caller provided an explicit user-selected
+	// project from the ambiguity result's available_projects list.
+	SourceUserSelectedAfterAmbiguousProject = "user_selected_after_ambiguous_project"
+	SourceRequestBody                       = "request_body" // REQ-414: project came from the request body (server-side, no filesystem path)
+	SourceConfig                            = "config"       // derived from .engram/config.json project_name
 )
 
 // noiseSet lists directory names that are skipped during child-repo scanning.