Fork a Claude conversation into a new worktree (#237)

## Summary

Lets a new worktree be seeded with an **existing Claude conversation**
instead of a hand-written summary prompt, so the new agent resumes
actually holding what was said rather than being briefed about it.

Two entry points:

- **UI** — a "fork this conversation" option on the new-worktree screen,
launched from a Chat tab.
- **MCP** — `create_worktree` gains `forkConversation: true`. Always
self-scoped: for Chat tabs the bridge's terminal id *is* the session id,
so both fork inputs are derived from the request header. Rejected up
front (before any git work) for terminal tabs, callers with no
transcript, and any combination with `prNumber`.

### The relocation preamble

The load-bearing piece. A forked transcript is full of edits to a
worktree the new agent isn't in, and the new branch is cut from the base
ref — so it carries neither the uncommitted work nor, usually, the
commits. `fork-relocation.ts` prepends a note stating where the agent is
now, where the history happened, and **what actually survived** —
computed from git, not templated. When git can't answer, it says so
explicitly rather than guessing.

## Verification

Forked a real conversation into a real worktree over both paths and read
what the resumed agent did.

The forking agent's `initialPrompt` asserted a plan file *would* be
present ("the commit is on main, so it should be there"). The forked
agent didn't take it on faith — it checked, found the file missing, and
diagnosed it exactly: *"this branch was cut from `7937032`, one commit
behind main, so commit `41da774` didn't come along."* It then verified
with `merge-base --is-ancestor`, fast-forwarded, re-read the plan, and
got to work. The preamble's "check before you build on anything you
edited earlier" did its job — and caught a wrong assumption the agent's
own past self had written.

The first end-to-end run **failed on the tool description, not the
plumbing**: given an explicit continuity request the agent still
hand-wrote a briefing, reasoning that a forked transcript "would mostly
be noise." The old decision test asked whether it *could* write a
sufficient briefing — a diligent agent always answers yes, so that test
only ever resolved to "don't fork." Replaced with "ask what the briefing
would have to *contain*" (`d32ce04`); the agent then forked on the
identical prompt.

## Test plan

- [x] `npm run typecheck`
- [x] `npx electron-vite build`
- [x] `npx vitest run` — new coverage in `fork-transcript.test.ts`,
`fork-relocation.test.ts`, `control-server.test.ts`,
`worktrees-fsm.test.ts` (pre-existing unrelated failures in `path-fix` /
`git-ops-state` only)
- [x] End-to-end fork over the UI path
- [x] End-to-end fork over the MCP path — matching `fork wrote` /
`spawn` session ids
- [x] Rejection paths: terminal tab, no transcript, `prNumber`
combination

## Notes for review

- API is `forkConversation: true` (self-scoped boolean) rather than a
caller-supplied session id — an agent can't reliably observe its own
session id, and cross-worktree forking would need a session→worktree
index nothing currently asks for. Easy to widen later.
- The MCP `POST /worktrees` branch path bypasses `WorktreesFSM` and
calls `addWorktree` directly, so it has no pending-list entry to guard
the async seeding window. `seedingWorktreePaths` claims the path instead
— without it the pane sweep re-opens the race fixed in `4dcf8b1`.

🤖 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

@@ -123,11 +123,18 @@ function callControl(method, path, body) {
   })
 }
 
+// Appended to create_worktree's description, and removed again by
+// stripForkAffordance when the feature is off. Kept as its own constant so the
+// two stay in sync — a literal that drifts would silently stop being stripped.
+const FORK_DESCRIPTION_SENTENCE =
+  ' The new tab normally starts as a blank conversation seeded with initialPrompt; set forkConversation to instead hand it a copy of THIS conversation to continue from.'
+
 const TOOLS = [
   {
     name: 'create_worktree',
     description:
-      "Create a new git worktree in a Harness-managed repo. Either create a brand-new branch (set branchName) OR check out an existing GitHub PR for review (set prNumber). Harness will open a new agent chat tab inside the new worktree automatically. Defaults to the caller's current repo when repoRoot is omitted.",
+      "Create a new git worktree in a Harness-managed repo. Either create a brand-new branch (set branchName) OR check out an existing GitHub PR for review (set prNumber). Harness will open a new agent chat tab inside the new worktree automatically. Defaults to the caller's current repo when repoRoot is omitted." +
+      FORK_DESCRIPTION_SENTENCE,
     inputSchema: {
       type: 'object',
       properties: {
@@ -172,6 +179,11 @@ const TOOLS = [
           type: 'string',
           description:
             'Optional display alias applied to the new worktree once creation succeeds. Same semantics as set_worktree_alias — trimmed and clamped to 80 chars, empty string is ignored. Useful when the user gave the task a memorable label ("call this one auth-refactor") so the sidebar/window title show that instead of the branch name.'
+        },
+        forkConversation: {
+          type: 'boolean',
+          description:
+            'Copy YOUR current conversation into the new worktree, so its agent resumes holding everything said here instead of starting blank. Only works when you are a Harness Chat tab with existing history; otherwise the call is rejected and you should retry without it. Cannot be combined with prNumber.\n\nFORK when the new worktree continues THIS thread of work. Strongest signal: the user asks for continuity — "pick up where we left off", "they should already know what we discussed", "carry on from here". Take that at face value; it is a request to fork, and answering it with a hand-written briefing instead is the wrong call. Also fork when the work leans on things that only exist in this conversation: what you already read and ruled out, why the user rejected an earlier approach, a design the two of you converged on over several turns.\n\nDO NOT FORK for a task that merely sits next to this one ("also fix the flaky test", "do the same on the other service"), for a clean retry after an approach failed, or for reviewing someone else\'s code. There the history is noise the new agent must read past.\n\nDeciding: do not ask yourself whether you COULD write a sufficient briefing — you almost always can, so that question always answers "no fork" and is useless. Ask instead what the briefing would have to contain. If it needs to relay specific findings, discarded options, or user decisions from this conversation, fork: the transcript already holds those, faithfully, and your summary of them will be lossier than you expect. If it would just be a task description someone could have written before this conversation started, do not fork.\n\nCost of forking, so you can weigh it: the transcript is full of your earlier file edits, but the new branch is cut from the base ref, so it does NOT contain your uncommitted work and may not contain your commits. Harness prepends a note telling the new agent where it now is and which of those changes actually survived, and it will spend a little effort re-verifying before it builds.\n\nWhen you fork, still pass initialPrompt — it lands right after that note and is what actually directs the new agent. Write it as a continuation ("now build the page we just planned, here") and do not re-explain what the conversation already contains.'
         }
       }
     }
@@ -523,16 +535,29 @@ const FULL_CONTROL_BROWSER_TOOLS = new Set([
   'show_cursor'
 ])
 
-let cachedBrowserPerms = null
-async function getBrowserPerms() {
-  if (cachedBrowserPerms) return cachedBrowserPerms
+// One /scope fetch backs every capability gate below. Defaults on failure are
+// permissive for browser tools (pre-existing behaviour) but the fork gate
+// defaults off — the setting is opt-in, and a server that doesn't report it
+// would reject the call anyway, so advertising it would only waste a turn.
+let cachedScope = null
+async function getScopeInfo() {
+  if (cachedScope) return cachedScope
   try {
-    const r = await callControl('GET', '/scope')
-    cachedBrowserPerms = (r && r.browser) || { enabled: true, mode: 'full' }
+    cachedScope = (await callControl('GET', '/scope')) || {}
   } catch {
-    cachedBrowserPerms = { enabled: true, mode: 'full' }
+    cachedScope = {}
   }
-  return cachedBrowserPerms
+  return cachedScope
+}
+
+async function getBrowserPerms() {
+  const s = await getScopeInfo()
+  return s.browser || { enabled: true, mode: 'full' }
+}
+
+async function getConversationForkEnabled() {
+  const s = await getScopeInfo()
+  return s.conversationFork ? s.conversationFork.enabled === true : false
 }
 
 function filterToolsByPerms(tools, perms) {
@@ -546,6 +571,20 @@ function filterToolsByPerms(tools, perms) {
   })
 }
 
+// Strip every trace of forking from create_worktree when it's disabled, rather
+// than advertising a parameter whose only outcome is a rejection.
+function stripForkAffordance(tools) {
+  return tools.map((t) => {
+    if (t.name !== 'create_worktree') return t
+    const { forkConversation, ...rest } = t.inputSchema.properties
+    return {
+      ...t,
+      description: t.description.replace(FORK_DESCRIPTION_SENTENCE, ''),
+      inputSchema: { ...t.inputSchema, properties: rest }
+    }
+  })
+}
+
 async function handleToolCall(name, args) {
   if (name === 'create_worktree') {
     const prNumber = args && args.prNumber
@@ -574,14 +613,19 @@ async function handleToolCall(name, args) {
       initialPrompt: args.initialPrompt,
       agentKind: args.agentKind,
       model: args.model,
-      alias: args.alias
+      alias: args.alias,
+      forkConversation: args.forkConversation === true
     })
     const agentLabel = args.agentKind === 'codex' ? 'Codex' : 'Claude'
     const modelSuffix = args.model ? ` (model: ${args.model})` : ''
     const aliasSuffix = args.alias && args.alias.trim() ? ` (alias: "${args.alias.trim()}")` : ''
+    const forkSuffix =
+      args.forkConversation === true
+        ? ' It resumes a copy of this conversation, and has been told where it is and which of your earlier changes came along.'
+        : ''
     return prNumber
       ? `Created worktree ${r.path} on branch ${r.branch} for PR #${prNumber}${aliasSuffix}. Harness will open a new ${agentLabel} chat tab in it${modelSuffix}.`
-      : `Created worktree ${r.path} on branch ${r.branch}${aliasSuffix}. Harness will open a new ${agentLabel} chat tab in it${modelSuffix}.`
+      : `Created worktree ${r.path} on branch ${r.branch}${aliasSuffix}. Harness will open a new ${agentLabel} chat tab in it${modelSuffix}.${forkSuffix}`
   }
   if (name === 'list_worktrees') {
     const q =
@@ -803,7 +847,9 @@ async function handle(msg) {
     if (method === 'tools/list') {
       logErr('tools/list received')
       const perms = await getBrowserPerms()
-      return { jsonrpc: '2.0', id, result: { tools: filterToolsByPerms(TOOLS, perms) } }
+      let tools = filterToolsByPerms(TOOLS, perms)
+      if (!(await getConversationForkEnabled())) tools = stripForkAffordance(tools)
+      return { jsonrpc: '2.0', id, result: { tools } }
     }
     if (method === 'tools/call') {
       logErr('tools/call received name=' + (params && params.name))

src/main/agents/claude.test.ts

@@ -69,6 +69,37 @@ describe('buildSpawnArgs', () => {
     expect(result).toContain('--append-system-prompt')
     expect(result).toContain("'\\''")
   })
+
+  const sessionPath = (cwd: string, id: string): string =>
+    join(homedir(), '.claude', 'projects', cwd.replace(/[^a-zA-Z0-9]/g, '-'), `${id}.jsonl`)
+
+  it('passes the initial prompt through on the --resume path', () => {
+    // A worktree forked from an existing conversation resumes a transcript
+    // AND needs its new instructions; dropping the prompt here left the
+    // agent sitting idle with history it was never told what to do with.
+    fsState.files.set(sessionPath('/tmp/test', 'abc'), '{}')
+    const result = buildSpawnArgs({ ...base, sessionId: 'abc', initialPrompt: 'do the thing' })
+    expect(result).toContain('--resume abc')
+    expect(result).toContain("'do the thing'")
+  })
+
+  it('omits a positional prompt on --resume when there is none', () => {
+    fsState.files.set(sessionPath('/tmp/test', 'abc'), '{}')
+    const result = buildSpawnArgs({ ...base, sessionId: 'abc' })
+    expect(result).toBe('claude --resume abc')
+  })
+
+  it('uses --session-id with the prompt when no transcript exists yet', () => {
+    const result = buildSpawnArgs({ ...base, sessionId: 'abc', initialPrompt: 'hello' })
+    expect(result).toContain('--session-id abc')
+    expect(result).toContain("'hello'")
+  })
+
+  it('shell-quotes the initial prompt on the resume path', () => {
+    fsState.files.set(sessionPath('/tmp/test', 'abc'), '{}')
+    const result = buildSpawnArgs({ ...base, sessionId: 'abc', initialPrompt: "it's got quotes" })
+    expect(result).toContain("'\\''")
+  })
 })
 
 describe('claude extractSessionId', () => {

src/main/agents/claude.ts

@@ -196,7 +196,8 @@ export function buildSpawnArgs(opts: AgentSpawnOpts): string {
   }
 
   const exists = sessionFileExists(opts.cwd, opts.sessionId)
-  if (exists) return `${cmd} --resume ${opts.sessionId}`
-  const base = `${cmd} --session-id ${opts.sessionId}`
+  const base = exists
+    ? `${cmd} --resume ${opts.sessionId}`
+    : `${cmd} --session-id ${opts.sessionId}`
   return opts.initialPrompt ? `${base} ${shellQuote(opts.initialPrompt)}` : base
 }

src/main/build-initial-state.ts

@@ -135,6 +135,7 @@ export function buildInitialAppState(
       wsTransportHost: config.wsTransportHost ?? '127.0.0.1',
       browserToolsEnabled: config.browserToolsEnabled !== false,
       browserToolsMode: config.browserToolsMode === 'view' ? 'view' : 'full',
+      conversationForkEnabled: config.conversationForkEnabled === true,
       defaultClaudeTabType: config.defaultClaudeTabType === 'json' ? 'json' : 'xterm',
       chatPromotionDismissed: config.chatPromotionDismissed === true,
       autoApprovePermissions: config.autoApprovePermissions === true,

src/main/claude-launch.test.ts

@@ -2,10 +2,17 @@ import { describe, it, expect } from 'vitest'
 import { buildClaudeLaunchSettings } from './claude-launch'
 import {
   DEFAULT_HARNESS_SYSTEM_PROMPT,
-  DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN
+  DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN,
+  HARNESS_SYSTEM_PROMPT_FORK_PARAGRAPH
 } from './persistence'
 import type { Worktree } from '../shared/state/worktrees'
 
+/** Conversation fork is opt-in, so the default prompt omits its paragraph. */
+const PROMPT_WITHOUT_FORK = DEFAULT_HARNESS_SYSTEM_PROMPT.replace(
+  `\n\n${HARNESS_SYSTEM_PROMPT_FORK_PARAGRAPH}`,
+  ''
+)
+
 function makeWorktree(overrides: Partial<Worktree> = {}): Worktree {
   return {
     path: '/tmp/repo/feat-x',
@@ -27,7 +34,29 @@ describe('buildClaudeLaunchSettings', () => {
       worktrees: [wt],
       config: {}
     })
-    expect(out.systemPrompt).toBe(DEFAULT_HARNESS_SYSTEM_PROMPT)
+    expect(out.systemPrompt).toBe(PROMPT_WITHOUT_FORK)
+  })
+
+  it('includes the fork paragraph only when conversationForkEnabled is true', () => {
+    const wt = makeWorktree()
+    const on = buildClaudeLaunchSettings({
+      cwd: wt.path,
+      worktrees: [wt],
+      config: { conversationForkEnabled: true }
+    })
+    expect(on.systemPrompt).toBe(DEFAULT_HARNESS_SYSTEM_PROMPT)
+    expect(on.systemPrompt).toContain(HARNESS_SYSTEM_PROMPT_FORK_PARAGRAPH)
+    expect(PROMPT_WITHOUT_FORK).not.toContain(HARNESS_SYSTEM_PROMPT_FORK_PARAGRAPH)
+  })
+
+  it('leaves a custom system prompt untouched when fork is disabled', () => {
+    const wt = makeWorktree()
+    const out = buildClaudeLaunchSettings({
+      cwd: wt.path,
+      worktrees: [wt],
+      config: { harnessSystemPrompt: 'MY PROMPT' }
+    })
+    expect(out.systemPrompt).toBe('MY PROMPT')
   })
 
   it('appends the main-worktree addition when isMain', () => {
@@ -38,7 +67,7 @@ describe('buildClaudeLaunchSettings', () => {
       config: {}
     })
     expect(out.systemPrompt).toBe(
-      `${DEFAULT_HARNESS_SYSTEM_PROMPT}\n\n${DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN}`
+      `${PROMPT_WITHOUT_FORK}\n\n${DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN}`
     )
   })
 

src/main/claude-launch.ts

@@ -1,7 +1,8 @@
 import type { Worktree } from '../shared/state/worktrees'
 import {
   DEFAULT_HARNESS_SYSTEM_PROMPT,
-  DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN
+  DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN,
+  HARNESS_SYSTEM_PROMPT_FORK_PARAGRAPH
 } from './persistence'
 
 export interface ClaudeLaunchConfig {
@@ -11,6 +12,7 @@ export interface ClaudeLaunchConfig {
   harnessSystemPromptMain?: string
   claudeTuiFullscreen?: boolean
   nameClaudeSessions?: boolean
+  conversationForkEnabled?: boolean
 }
 
 export interface ClaudeLaunchSettings {
@@ -36,7 +38,10 @@ export function buildClaudeLaunchSettings(input: {
 
   let systemPrompt: string | undefined
   if (config.harnessSystemPromptEnabled !== false) {
-    const base = config.harnessSystemPrompt || DEFAULT_HARNESS_SYSTEM_PROMPT
+    let base = config.harnessSystemPrompt || DEFAULT_HARNESS_SYSTEM_PROMPT
+    if (config.conversationForkEnabled !== true) {
+      base = base.replace(`\n\n${HARNESS_SYSTEM_PROMPT_FORK_PARAGRAPH}`, '')
+    }
     if (isMain) {
       const mainAddition =
         config.harnessSystemPromptMain || DEFAULT_HARNESS_SYSTEM_PROMPT_MAIN

src/main/control-server.test.ts

@@ -22,6 +22,9 @@ const clearAlias = vi.fn<(worktreePath: string) => void>()
 const CALLER_TERMINAL = 'terminal-abc'
 const CALLER_WORKTREE = '/repo/wt/callers-tree'
 const EXPLICIT_WORKTREE = '/repo/wt/other'
+/** Scoped to a worktree like a chat tab, but with no transcript on disk —
+ * how a plain terminal tab looks to the fork path. */
+const NO_TRANSCRIPT_TERMINAL = 'terminal-no-transcript'
 
 const scope: CallerScope = {
   terminalId: CALLER_TERMINAL,
@@ -30,14 +33,21 @@ const scope: CallerScope = {
   isMain: false
 }
 
+/** Mutable so a test can flip the setting off without restarting the server —
+ * mirrors how the real dep re-reads config per request. */
+let conversationForkEnabled = true
+
 const deps: ControlServerDeps = {
   getRepoRoots: () => ['/repo'],
   getWorktreeBase: () => 'remote',
   getPrReviewPrompt: () => '',
   broadcast: () => {},
   runWorktreeSetup: async () => {},
   runPendingPRWorktree: async () => ({ ok: false, error: 'not used in these tests' }),
-  resolveCallerScope: (terminalId) => (terminalId === CALLER_TERMINAL ? scope : null),
+  resolveCallerScope: (terminalId) =>
+    terminalId === CALLER_TERMINAL || terminalId === NO_TRANSCRIPT_TERMINAL ? scope : null,
+  hasForkableTranscript: (sessionId) => sessionId === CALLER_TERMINAL,
+  getConversationForkEnabled: () => conversationForkEnabled,
   getBrowserPerms: () => ({ enabled: false, mode: 'full' }),
   browser: {
     listTabsForWorktree: () => [],
@@ -94,15 +104,15 @@ async function call(
   return { status: res.status, json }
 }
 
-describe('control-server /aliases endpoint', () => {
-  beforeAll(async () => {
-    await startControlServer(deps)
-    const info = getControlServerInfo()
-    if (!info) throw new Error('control server failed to start')
-    baseUrl = `http://127.0.0.1:${info.port}`
-    token = info.token
-  })
+beforeAll(async () => {
+  await startControlServer(deps)
+  const info = getControlServerInfo()
+  if (!info) throw new Error('control server failed to start')
+  baseUrl = `http://127.0.0.1:${info.port}`
+  token = info.token
+})
 
+describe('control-server /aliases endpoint', () => {
   it('POST /aliases with explicit worktreePath dispatches setAlias', async () => {
     setAlias.mockClear()
     const r = await call('POST', '/aliases', {
@@ -184,3 +194,58 @@ describe('control-server /aliases endpoint', () => {
     expect(clearAlias).toHaveBeenCalledWith(CALLER_WORKTREE)
   })
 })
+
+// These all reject before addWorktree runs, so no git work happens. The
+// accept path isn't covered here — it would create a real worktree.
+describe('control-server POST /worktrees forkConversation', () => {
+  it('rejects a caller whose terminal has no forkable transcript', async () => {
+    const r = await call(
+      'POST',
+      '/worktrees',
+      { branchName: 'spinoff', forkConversation: true },
+      { terminalId: NO_TRANSCRIPT_TERMINAL }
+    )
+    expect(r.status).toBe(400)
+    expect(r.json.error).toMatch(/only available from a Harness Chat tab/)
+  })
+
+  it('rejects a caller with no resolvable scope', async () => {
+    const r = await call(
+      'POST',
+      '/worktrees',
+      { branchName: 'spinoff', forkConversation: true },
+      { terminalId: 'unknown-terminal' }
+    )
+    expect(r.status).toBe(400)
+    expect(r.json.error).toMatch(/only available from a Harness Chat tab/)
+  })
+
+  it('rejects forkConversation combined with prNumber', async () => {
+    const r = await call('POST', '/worktrees', { prNumber: 7, forkConversation: true })
+    expect(r.status).toBe(400)
+    expect(r.json.error).toMatch(/cannot be combined with prNumber/)
+  })
+
+  it('rejects forkConversation into an agent that cannot resume a transcript', async () => {
+    for (const agentKind of ['codex', 'cursor']) {
+      const r = await call('POST', '/worktrees', {
+        branchName: 'spinoff',
+        agentKind,
+        forkConversation: true
+      })
+      expect(r.status).toBe(400)
+      expect(r.json.error).toMatch(/only Claude Code can resume a forked transcript/)
+    }
+  })
+
+  it('rejects forkConversation when the setting is disabled', async () => {
+    conversationForkEnabled = false
+    try {
+      const r = await call('POST', '/worktrees', { branchName: 'spinoff', forkConversation: true })
+      expect(r.status).toBe(400)
+      expect(r.json.error).toMatch(/disabled in Harness settings/)
+    } finally {
+      conversationForkEnabled = true
+    }
+  })
+})