Tag other worktrees from the @ menu in Chat tabs (#257)

## Summary

- The `@` menu in Chat tabs now lists other worktrees above the file
matches, so you can point at one from the composer now that agents have
`send_message`.
- Picking a worktree inserts `@worktree:<branch>`. The `worktree:`
prefix keeps the token from reading as a relative file path — a bare
branch name sends the agent looking on disk before it guesses what you
meant. `resolveWorktreeQuery` strips the prefix, so the token resolves
whether the agent passes it verbatim or trims it first.
- Rows only appear when the **worktree messaging** setting is on
(default off) — that setting is what grants the agent `send_message` at
all, so tagging a worktree without it would be a dead end.

## Notes

Matching is substring rather than fuzzy. Worktree rows sort above file
matches, so a loose subsequence hit — `@src` matching s…r…c somewhere
inside a branch name — would take row 0 and steal the Enter key from the
file the user was actually reaching for. Matching against the full
`worktree:<branch>` label also means typing `@worktree` lists them all,
which is how the feature gets discovered.

Bare `@` with no query still shows files only, so the existing
file-mention flow is untouched.

## Test plan

- [x] `npm run typecheck` and `npx electron-vite build` clean
- [x] New `resolveWorktreeQuery` cases for the `worktree:` prefix
(`src/main/chat-delivery.test.ts`)
- [x] Full `npx vitest run` — 8 failures are pre-existing
environment-dependent tests (rebase state, `fs.watch`, login-shell
PATH), untouched by this change
- [ ] Manual: with worktree messaging on, type `@worktree` in a Chat tab
and confirm the rows list, alias shows as the description, and picking
one inserts `@worktree:<branch>`
- [ ] Manual: with the setting off, confirm no worktree rows appear
- [ ] Manual: confirm bare `@` still leads with files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: frenchie4111

resources/mcp-bridge.js

@@ -253,7 +253,7 @@ const TOOLS = [
         worktree: {
           type: 'string',
           description:
-            'Which worktree to message — its display alias, its branch name, or its absolute path. Call list_worktrees first if you are unsure what exists.'
+            'Which worktree to message — a `<repo>/<branch>` handle, its display alias, or its absolute path. A bare branch name works only when it is unique across every open repo, which `main` never is. A `@worktree:<repo>/<branch>` token in the user\'s message is a worktree mention picked from the composer; pass it here as-is (with or without the `worktree:` prefix). Call list_worktrees first if you are unsure what exists.'
         },
         message: {
           type: 'string',

src/main/chat-delivery.test.ts

@@ -110,6 +110,26 @@ describe('resolveWorktreeQuery', () => {
     expect(resolveWorktreeQuery(state, 'feat/billing')).toEqual({ path: B })
   })
 
+  it('strips the worktree: prefix from a composer mention token', () => {
+    expect(resolveWorktreeQuery(state, 'worktree:repo/feat/billing')).toEqual({ path: B })
+    expect(resolveWorktreeQuery(state, 'Worktree: Auth Refactor')).toEqual({ path: A })
+  })
+
+  it('disambiguates a branch shared across repos via the <repo>/<branch> handle', () => {
+    const twoRepos = makeState({
+      worktrees: [
+        worktree(A, 'main', { repoRoot: '/src/harness' }),
+        worktree(B, 'main', { repoRoot: '/src/chicken' })
+      ]
+    })
+    expect(resolveWorktreeQuery(twoRepos, 'harness/main')).toEqual({ path: A })
+    expect(resolveWorktreeQuery(twoRepos, 'worktree:chicken/main')).toEqual({ path: B })
+    // The bare branch is still ambiguous, and stays an error rather than a guess.
+    expect(resolveWorktreeQuery(twoRepos, 'main')).toEqual({
+      error: '"main" matches 2 worktrees — pass the absolute path instead'
+    })
+  })
+
   it('errors on an unknown handle', () => {
     expect(resolveWorktreeQuery(state, 'nope')).toEqual({
       error: 'no worktree matching "nope"'

src/main/chat-delivery.ts

@@ -1,5 +1,6 @@
 import type { AppState } from '../shared/state'
 import { getLeaves } from '../shared/state/terminals'
+import { worktreeHandle } from '../shared/state/worktrees'
 
 export interface ChatDeliveryDeps {
   /** Injects a user turn into a running json-mode chat session. */
@@ -56,15 +57,24 @@ function pickSleptTab(state: AppState, worktreePath: string): string | null {
   return fallback
 }
 
+const WORKTREE_HANDLE_PREFIX = 'worktree:'
+
 /** Resolve a caller-supplied worktree handle. Absolute path wins outright;
- *  otherwise alias and branch are matched case-insensitively. An ambiguous
- *  handle is an error rather than a guess — silently picking one of two
- *  worktrees would deliver a message somewhere the sender didn't intend. */
+ *  otherwise a `<repo>/<branch>` handle, alias, and bare branch are matched
+ *  case-insensitively. An ambiguous handle is an error rather than a guess —
+ *  silently picking one of two worktrees would deliver a message somewhere
+ *  the sender didn't intend. */
 export function resolveWorktreeQuery(
   state: AppState,
   query: string
 ): { path: string } | { error: string } {
-  const q = query.trim()
+  // The chat composer's @-mention inserts `@worktree:<repo>/<branch>`, and
+  // agents routinely pass that token through verbatim. Strip the prefix so
+  // it resolves instead of 404ing on a handle we handed them ourselves.
+  let q = query.trim()
+  if (q.toLowerCase().startsWith(WORKTREE_HANDLE_PREFIX)) {
+    q = q.slice(WORKTREE_HANDLE_PREFIX.length).trim()
+  }
   if (!q) return { error: 'worktree required' }
   // A prunable worktree's directory is already gone, so nothing can be
   // running in it to receive the message.
@@ -74,7 +84,11 @@ export function resolveWorktreeQuery(
   const matches = new Set<string>()
   for (const w of list) {
     const alias = state.aliases.byPath[w.path]
-    if (alias?.toLowerCase() === lower || w.branch.toLowerCase() === lower) {
+    if (
+      alias?.toLowerCase() === lower ||
+      w.branch.toLowerCase() === lower ||
+      worktreeHandle(w.repoRoot, w.branch).toLowerCase() === lower
+    ) {
       matches.add(w.path)
     }
   }

src/renderer/components/JsonModeChat.tsx

@@ -34,7 +34,7 @@ import {
   GitBranchPlus
 } from 'lucide-react'
 import { openForkIntoWorktree } from './NewWorktreeScreen'
-import { useJsonClaudeSession, useSettings } from '../store'
+import { useAliases, useJsonClaudeSession, useSettings, useWorktrees } from '../store'
 import { useBackend } from '../backend'
 import { useJsonClaudeApprovals } from '../hooks/useJsonClaudeApprovals'
 import { JsonClaudeApprovalCard } from './JsonClaudeApprovalCard'
@@ -48,6 +48,7 @@ import { buildChildrenMap, isSubAgentToolName } from './json-mode-cards/grouping
 import { JsonModeMentionPopover, type MentionPopoverItem } from './JsonModeMentionPopover'
 import { JsonModeChatImageThumb } from './JsonModeChatImageThumb'
 import { fuzzyMatch } from '../fuzzy'
+import { worktreeHandle } from '../../shared/state/worktrees'
 import { CLAUDE_MODELS } from '../../shared/agent-registry'
 import {
   QUESTION_TOOL_NAME,
@@ -193,6 +194,49 @@ const FILE_CACHE = new Map<string, { files: string[]; ts: number }>()
 const FILE_CACHE_TTL_MS = 10_000
 const MAX_MENTION_RESULTS = 50
 
+// `@worktree:<repo>/<branch>` is what a worktree mention inserts. The prefix
+// keeps the token from reading as a relative file path — without it the
+// agent tries to Read the branch name off disk before guessing it meant a
+// worktree. resolveWorktreeQuery (main/chat-delivery.ts) strips the same
+// prefix, so the token can be passed straight to send_message.
+const WORKTREE_MENTION_PREFIX = 'worktree:'
+const MAX_WORKTREE_MENTION_RESULTS = 5
+
+// Substring rather than fuzzy: worktree rows sort above the file matches,
+// so a loose subsequence hit ("src" matching s…r…c somewhere in a branch)
+// would steal the default selection from the file the user was after.
+// Matching against the full `worktree:<branch>` label means typing
+// `@worktree` lists them all, which is how the feature is discovered.
+function matchWorktreeMentions(
+  query: string,
+  targets: { path: string; handle: string; alias?: string }[]
+): MentionPopoverItem[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return []
+  const ranked: { at: number; item: MentionPopoverItem }[] = []
+  for (const t of targets) {
+    const label = `${WORKTREE_MENTION_PREFIX}${t.handle}`
+    const at = label.toLowerCase().indexOf(q)
+    const aliasHit = t.alias?.toLowerCase().includes(q) ?? false
+    if (at === -1 && !aliasHit) continue
+    ranked.push({
+      at: at === -1 ? Number.MAX_SAFE_INTEGER : at,
+      item: {
+        key: `worktree:${t.path}`,
+        label,
+        labelMatchIndices:
+          at === -1
+            ? undefined
+            : Array.from({ length: q.length }, (_, i) => at + i),
+        description: t.alias,
+        icon: <GitBranch className="icon-xs" />
+      }
+    })
+  }
+  ranked.sort((a, b) => a.at - b.at)
+  return ranked.slice(0, MAX_WORKTREE_MENTION_RESULTS).map((r) => r.item)
+}
+
 // Pre-baked descriptions for built-in slash commands. Skills + plugin
 // commands appear in the menu via session.slashCommands (sourced from
 // claude's system/init event) but don't have a description until we
@@ -1185,8 +1229,11 @@ export function JsonModeChat({ sessionId, worktreePath, mode = 'awake' }: JsonMo
     jsonModeSendOnEnter: sendOnEnter,
     autoScrollToBottom,
     defaultClaudeTabType,
-    conversationForkEnabled
+    conversationForkEnabled,
+    worktreeMessagingEnabled
   } = useSettings()
+  const worktrees = useWorktrees()
+  const aliases = useAliases()
   const cameFromTerminalDefault = defaultClaudeTabType === 'xterm'
   const isMac =
     typeof window !== 'undefined' &&
@@ -1918,6 +1965,19 @@ export function JsonModeChat({ sessionId, worktreePath, mode = 'awake' }: JsonMo
 
   const currentModelDisplay = claudeModelDisplayName(session?.currentModel)
 
+  // Gated on the setting that grants the agent send_message in the first
+  // place — tagging a worktree it has no tool to reach is a dead end.
+  const worktreeMentionTargets = useMemo(() => {
+    if (!worktreeMessagingEnabled) return []
+    return worktrees.list
+      .filter((w) => !w.prunable && w.path !== worktreePath)
+      .map((w) => ({
+        path: w.path,
+        handle: worktreeHandle(w.repoRoot, w.branch),
+        alias: aliases.byPath[w.path]
+      }))
+  }, [worktreeMessagingEnabled, worktrees.list, aliases.byPath, worktreePath])
+
   const mentionItems = useMemo<MentionPopoverItem[]>(() => {
     if (mentionDismissed === draft) return []
     if (modelPickerTrigger !== null) {
@@ -2002,7 +2062,7 @@ export function JsonModeChat({ sessionId, worktreePath, mode = 'awake' }: JsonMo
         }
       })
     }
-    if (mentionTrigger !== null && files.length > 0) {
+    if (mentionTrigger !== null) {
       const q = mentionTrigger.query
       let ranked: { item: string; indices?: number[] }[]
       if (q.length === 0) {
@@ -2012,19 +2072,21 @@ export function JsonModeChat({ sessionId, worktreePath, mode = 'awake' }: JsonMo
           .slice(0, MAX_MENTION_RESULTS)
           .map((r) => ({ item: r.item, indices: r.indices }))
       }
-      return ranked.map((r) => ({
+      const fileRows = ranked.map((r) => ({
         key: r.item,
         label: r.item,
         labelMatchIndices: r.indices,
         icon: <FileText className="icon-xs" />
       }))
+      return [...matchWorktreeMentions(q, worktreeMentionTargets), ...fileRows]
     }
     return []
   }, [
     slashTrigger,
     mentionTrigger,
     modelPickerTrigger,
     files,
+    worktreeMentionTargets,
     draft,
     mentionDismissed,
     session?.slashCommands,

src/shared/state/worktrees.ts

@@ -23,6 +23,14 @@ export interface Worktree {
   prunableReason?: string
 }
 
+/** Handle for a worktree in agent-facing text: `<repo>/<branch>`. Branch
+ *  alone collides the moment two repos are open — every repo has a `main` —
+ *  and an ambiguous handle is a hard error at resolve time, not a guess.
+ *  Shared so the composer's @-mention and resolveWorktreeQuery agree. */
+export function worktreeHandle(repoRoot: string, branch: string): string {
+  return `${repoRoot.split('/').pop() || repoRoot}/${branch}`
+}
+
 /** Merge per-repo `listWorktrees` results into a flat list, preserving the
  * caller's prior slice for any repo whose lookup failed (indicated by null).
  * Purpose: a transient `git worktree list` failure for one repo shouldn't