feat(task): generate a session title from the first message

src/core/task-persistence/TaskHistoryStore.ts

@@ -1024,6 +1024,32 @@
 		})
 	}
 
+	/**
+	 * Set the title of a history item only when it has no title yet, inside a
+	 * single lock acquisition (in-process write lock plus the per-task file
+	 * lock in `safeWriteJson`). Used by the background session-title flow so a
+	 * generated title can never overwrite a title the user set by hand.
+	 *
+	 * @returns The updated item when a title was written, or `undefined` when
+	 * the item already has a title (which is left untouched).
+	 * @throws If the task ID is not present in the cache.
+	 */
+	public setTitleIfEmpty(taskId: string, title: string): Promise<HistoryItem | undefined> {
+		return this.withLock(async () => {
+			const current = this.cache.get(taskId)
+			if (!current) {
+				throw new Error(`[TaskHistoryStore] setTitleIfEmpty: task ${taskId} not found in cache`)
+			}
+			if (current.title && current.title.trim()) {
+				return undefined
+			}
+			// Deep-copy so the write cannot mutate cached state before persistence.
+			const updated = { ...structuredClone(current), title }
+			await this.upsertCore(updated)
+			return updated
+		})
+	}
+
 	/**
 	 * Update two related HistoryItems within a single in-process lock acquisition.
 	 * Both updaters run synchronously (no I/O, no lock re-entry). Both writes

src/core/task-persistence/__tests__/TaskHistoryStore.crossInstance.spec.ts

@@ -418,4 +418,72 @@ describe("TaskHistoryStore cross-instance safety", () => {
 		// B wrote last, so B's value wins.
 		expect(final.totalCost).toBe(2.0)
 	})
+
+	describe("setTitleIfEmpty (background session title)", () => {
+		it("writes the title when the item has none", async () => {
+			await storeA.initialize()
+			const item = makeHistoryItem({ id: "title-empty" })
+			await storeA.upsert(item)
+
+			const written = await storeA.setTitleIfEmpty("title-empty", "Generated title")
+
+			expect(written).toMatchObject({ id: "title-empty", title: "Generated title" })
+			expect(storeA.get("title-empty")?.title).toBe("Generated title")
+		})
+
+		it("keeps a title the user set by hand", async () => {
+			await storeA.initialize()
+			const item = makeHistoryItem({ id: "title-manual" })
+			await storeA.upsert(item)
+			await storeA.upsert({ ...item, title: "My own title" })
+
+			await expect(storeA.setTitleIfEmpty("title-manual", "Generated title")).resolves.toBeUndefined()
+
+			expect(storeA.get("title-manual")?.title).toBe("My own title")
+		})
+
+		it("throws when the task is not in the cache", async () => {
+			await storeA.initialize()
+
+			await expect(storeA.setTitleIfEmpty("missing-task", "Generated title")).rejects.toThrow(
+				"task missing-task not found in cache",
+			)
+		})
+
+		it("protects a manual title written by another instance", async () => {
+			await storeA.initialize()
+			await storeB.initialize()
+
+			const item = makeHistoryItem({ id: "shared-rename" })
+			await storeA.upsert(item)
+			await storeB.reconcile()
+
+			// The user renames in window A; window B's background generation finishes later.
+			await storeA.upsert({ ...item, title: "Renamed by user" })
+			await storeB.reconcile({ forceRefresh: true })
+
+			await expect(storeB.setTitleIfEmpty("shared-rename", "Generated title")).resolves.toBeUndefined()
+			expect(storeB.get("shared-rename")?.title).toBe("Renamed by user")
+
+			const filePath = path.join(tmpDir, "tasks", "shared-rename", GlobalFileNames.historyItem)
+			const final = JSON.parse(await fs.readFile(filePath, "utf8")) as HistoryItem
+			expect(final.title).toBe("Renamed by user")
+		})
+
+		it("lands a generated title from another instance on the shared task file", async () => {
+			await storeA.initialize()
+			await storeB.initialize()
+
+			const item = makeHistoryItem({ id: "shared-generated" })
+			await storeA.upsert(item)
+			await storeB.reconcile()
+
+			const written = await storeB.setTitleIfEmpty("shared-generated", "Generated title")
+			expect(written).toBeDefined()
+
+			// The write goes through the per-task file lock, so the peer sees it.
+			await storeA.invalidate("shared-generated")
+			expect(storeA.get("shared-generated")?.title).toBe("Generated title")
+		})
+	})
 })

src/core/task/Task.ts

@@ -7,6 +7,7 @@
 
 import { AskIgnoredError } from "./AskIgnoredError"
 import { RateLimitClock, createRateLimitClock } from "./RateLimitClock"
+import { generateSessionTitle } from "./session-title"
 
 import { Anthropic } from "@anthropic-ai/sdk"
 import OpenAI from "openai"
@@ -286,6 +287,9 @@
 	}
 }
 
+// Literal, not the vscode enum: specs that mock "vscode" without ExtensionMode would throw on the read.
+const EXTENSION_MODE_TEST = 3
+
 export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 	readonly taskId: string
 	readonly rootTaskId?: string
@@ -3110,6 +3114,11 @@
 
 			await this.say("text", task, images)
 
+			// Generate a session title in the background (fire-and-forget) so the
+			// task list shows a short title without delaying the task. Subtasks and
+			// resumed tasks keep their existing names.
+			this.generateSessionTitleInBackground(task ?? "")
+
 			// Check for too many MCP tools and warn the user
 			const { enabledToolCount, enabledServerCount } = await this.getEnabledMcpToolsCount()
 			if (enabledToolCount > MAX_MCP_TOOLS_THRESHOLD) {
@@ -3183,6 +3192,31 @@
 		}
 	}
 
+	/**
+	 * Fire-and-forget session title generation for a new root task.
+	 *
+	 * Runs after the first user message is stored. A generated title is written
+	 * only when the history item has no title yet, so a title the user set by
+	 * hand is never replaced. Subtasks and resumed tasks keep their existing
+	 * names. Failures are logged and never shown in the chat.
+	 */
+	private generateSessionTitleInBackground(firstMessage: string): void {
+		if (!firstMessage || this.parentTaskId || this._isHistoryTask) {
+			return
+		}
+
+		const provider = this.providerRef.deref()
+		if (!provider || provider.context.extensionMode === EXTENSION_MODE_TEST) {
+			return
+		}
+
+		void generateSessionTitle(this.api, firstMessage, { taskId: this.taskId })
+			.then((title) => provider.applyGeneratedSessionTitle(this.taskId, title))
+			.catch((error) => {
+				console.error(`[Task#generateSessionTitleInBackground] failed for ${this.taskId}:`, error)
+			})
+	}
+
 	private async resumeTaskFromHistory() {
 		try {
 			const modifiedClineMessages = [...(await this.getSavedClineMessages())]