From c663e68ca23115ac84702ef9f4e6dba05fa7c3ac Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Fri, 22 May 2026 17:00:31 -0600
Subject: [PATCH 1/7] feat: create_worktree MCP tool supports prNumber for
 PR-review worktrees
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lets an agent spin up a worktree checked out at a PR's head in one tool
call — same path as the UI's "Open PR as worktree" flow. The control
server's POST /worktrees handler now accepts `prNumber` and routes to
WorktreesFSM.runPendingPR, which fetches refs/pull/<n>/head into a local
branch named after the PR head (with -pr-<n> suffix if taken). The MCP
tool schema documents both paths; either branchName OR prNumber is
required, and prNumber wins when both are set.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 resources/mcp-bridge.js      |  39 ++++--
 resources/mcp-bridge.test.js | 245 +++++++++++++++++++++++++++++++++++
 src/main/control-server.ts   |  44 ++++++-
 src/main/index.ts            |  25 ++++
 src/main/worktrees-fsm.ts    |   9 +-
 5 files changed, 342 insertions(+), 20 deletions(-)
 create mode 100644 resources/mcp-bridge.test.js

diff --git a/resources/mcp-bridge.js b/resources/mcp-bridge.js
index 7c688b64..fc537054 100644
--- a/resources/mcp-bridge.js
+++ b/resources/mcp-bridge.js
@@ -75,13 +75,20 @@ const TOOLS = [
   {
     name: 'create_worktree',
     description:
-      "Create a new git worktree in a Harness-managed repo. Harness will open a new Claude 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 Claude chat tab inside the new worktree automatically. Defaults to the caller's current repo when repoRoot is omitted.",
     inputSchema: {
       type: 'object',
       properties: {
         branchName: {
           type: 'string',
-          description: 'Name of the new branch to create for the worktree.'
+          description:
+            'Name of the new branch to create for the worktree. Required when not creating from a PR.'
+        },
+        prNumber: {
+          type: 'integer',
+          minimum: 1,
+          description:
+            'GitHub PR number to check out for review. When set, Harness fetches refs/pull/<n>/head into a local branch named after the PR head (or `<headBranch>-pr-<n>` if taken locally) and opens a worktree against it. Useful for "review this PR" workflows.'
         },
         repoRoot: {
           type: 'string',
@@ -91,15 +98,14 @@ const TOOLS = [
         baseBranch: {
           type: 'string',
           description:
-            "Branch to fork the new worktree from. Defaults to the repo's configured base."
+            "Branch to fork the new worktree from. Defaults to the repo's configured base. Ignored when prNumber is provided."
         },
         initialPrompt: {
           type: 'string',
           description:
-            'A prompt to automatically send to the Claude chat tab when it opens in the new worktree.'
+            'A prompt to automatically send to the Claude chat tab when it opens in the new worktree. Useful for "review this PR for X" or "implement feature Y" prompts.'
         }
-      },
-      required: ['branchName']
+      }
     }
   },
   {
@@ -438,21 +444,26 @@ function filterToolsByPerms(tools, perms) {
 
 async function handleToolCall(name, args) {
   if (name === 'create_worktree') {
-    if (!args || !args.branchName) throw new Error('branchName is required')
+    const prNumber = args && args.prNumber
+    if (!args || (!args.branchName && !prNumber)) {
+      throw new Error('branchName or prNumber is required')
+    }
+    if (prNumber !== undefined && prNumber !== null) {
+      if (!Number.isInteger(prNumber) || prNumber <= 0) {
+        throw new Error('prNumber must be a positive integer')
+      }
+    }
     const r = await callControl('POST', '/worktrees', {
       terminalId: TERMINAL_ID,
       repoRoot: args.repoRoot,
       branchName: args.branchName,
+      prNumber: prNumber,
       baseBranch: args.baseBranch,
       initialPrompt: args.initialPrompt
     })
-    return (
-      'Created worktree ' +
-      r.path +
-      ' on branch ' +
-      r.branch +
-      '. Harness will open a new Claude chat tab in it.'
-    )
+    return prNumber
+      ? `Created worktree ${r.path} on branch ${r.branch} for PR #${prNumber}. Harness will open a new Claude chat tab in it.`
+      : `Created worktree ${r.path} on branch ${r.branch}. Harness will open a new Claude chat tab in it.`
   }
   if (name === 'list_worktrees') {
     const q =
diff --git a/resources/mcp-bridge.test.js b/resources/mcp-bridge.test.js
new file mode 100644
index 00000000..11dacc96
--- /dev/null
+++ b/resources/mcp-bridge.test.js
@@ -0,0 +1,245 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { createServer } from 'http'
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const BRIDGE = join(__dirname, 'mcp-bridge.js')
+
+function startStub(handler) {
+  return new Promise((resolve) => {
+    const captured = []
+    const server = createServer((req, res) => {
+      const chunks = []
+      req.on('data', (c) => chunks.push(c))
+      req.on('end', () => {
+        const body = chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf-8')) : {}
+        captured.push({
+          method: req.method,
+          url: req.url,
+          auth: req.headers.authorization,
+          terminalId: req.headers['x-harness-terminal-id'],
+          body
+        })
+        try {
+          handler(req, body, res, captured)
+        } catch (e) {
+          res.writeHead(500, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ error: String(e) }))
+        }
+      })
+    })
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port
+      resolve({ port, captured, close: () => new Promise((r) => server.close(() => r())) })
+    })
+  })
+}
+
+function spawnBridge(port, token) {
+  const proc = spawn(process.execPath, [BRIDGE], {
+    env: {
+      ...process.env,
+      HARNESS_PORT: String(port),
+      HARNESS_TOKEN: token,
+      HARNESS_TERMINAL_ID: 'test-terminal'
+    },
+    stdio: ['pipe', 'pipe', 'pipe']
+  })
+  let stdoutBuf = ''
+  const responses = []
+  const pending = []
+  proc.stdout.on('data', (chunk) => {
+    stdoutBuf += chunk.toString()
+    let idx
+    while ((idx = stdoutBuf.indexOf('\n')) !== -1) {
+      const line = stdoutBuf.slice(0, idx)
+      stdoutBuf = stdoutBuf.slice(idx + 1)
+      if (!line.trim()) continue
+      try {
+        const msg = JSON.parse(line)
+        if (pending.length) {
+          pending.shift()(msg)
+        } else {
+          responses.push(msg)
+        }
+      } catch {
+        /* ignore non-JSON */
+      }
+    }
+  })
+  proc.stderr.on('data', () => {
+    /* swallow */
+  })
+  function send(msg) {
+    proc.stdin.write(JSON.stringify(msg) + '\n')
+  }
+  function next() {
+    return new Promise((resolve) => {
+      if (responses.length) resolve(responses.shift())
+      else pending.push(resolve)
+    })
+  }
+  function kill() {
+    proc.kill()
+    return new Promise((resolve) => proc.once('exit', () => resolve()))
+  }
+  return { send, next, kill, proc }
+}
+
+describe('mcp-bridge create_worktree', () => {
+  let stub
+  let bridge
+
+  afterEach(async () => {
+    if (bridge) await bridge.kill()
+    if (stub) await stub.close()
+  })
+
+  it('forwards prNumber to POST /worktrees and reports PR # in result text', async () => {
+    stub = await startStub((req, body, res) => {
+      if (req.url === '/scope') {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        return res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ path: '/tmp/wt', branch: 'feature/pr-head' }))
+    })
+    bridge = spawnBridge(stub.port, 'secret-token')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: {
+        name: 'create_worktree',
+        arguments: { prNumber: 47, initialPrompt: 'review please' }
+      }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBeFalsy()
+    expect(response.result.content[0].text).toContain('PR #47')
+    expect(response.result.content[0].text).toContain('/tmp/wt')
+    expect(response.result.content[0].text).toContain('feature/pr-head')
+
+    const postCall = stub.captured.find((c) => c.method === 'POST' && c.url === '/worktrees')
+    expect(postCall).toBeDefined()
+    expect(postCall.auth).toBe('Bearer secret-token')
+    expect(postCall.terminalId).toBe('test-terminal')
+    expect(postCall.body.prNumber).toBe(47)
+    expect(postCall.body.initialPrompt).toBe('review please')
+  })
+
+  it('still supports the new-branch flow when prNumber is absent', async () => {
+    stub = await startStub((req, body, res) => {
+      if (req.url === '/scope') {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        return res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ path: '/tmp/wt-new', branch: 'mybranch' }))
+    })
+    bridge = spawnBridge(stub.port, 'tok')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: {
+        name: 'create_worktree',
+        arguments: { branchName: 'mybranch' }
+      }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBeFalsy()
+    const text = response.result.content[0].text
+    expect(text).toContain('/tmp/wt-new')
+    expect(text).toContain('mybranch')
+    expect(text).not.toContain('PR #')
+
+    const postCall = stub.captured.find((c) => c.method === 'POST' && c.url === '/worktrees')
+    expect(postCall.body.branchName).toBe('mybranch')
+    expect(postCall.body.prNumber).toBeUndefined()
+  })
+
+  it('returns an error when neither branchName nor prNumber is provided', async () => {
+    stub = await startStub((req, body, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+    })
+    bridge = spawnBridge(stub.port, 'tok')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: { name: 'create_worktree', arguments: {} }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBe(true)
+    expect(response.result.content[0].text).toMatch(/branchName or prNumber/)
+  })
+
+  it('rejects non-integer prNumber locally without hitting the server', async () => {
+    stub = await startStub((req, body, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+    })
+    bridge = spawnBridge(stub.port, 'tok')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: { name: 'create_worktree', arguments: { prNumber: -3 } }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBe(true)
+    expect(response.result.content[0].text).toMatch(/positive integer/)
+    const postCall = stub.captured.find((c) => c.method === 'POST' && c.url === '/worktrees')
+    expect(postCall).toBeUndefined()
+  })
+
+  it('surfaces server-side PR failures back to the caller', async () => {
+    stub = await startStub((req, body, res) => {
+      if (req.url === '/scope') {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        return res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+      }
+      res.writeHead(422, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ error: "Couldn't fetch PR #99999 from GitHub" }))
+    })
+    bridge = spawnBridge(stub.port, 'tok')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: {
+        name: 'create_worktree',
+        arguments: { prNumber: 99999 }
+      }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBe(true)
+    expect(response.result.content[0].text).toMatch(/HTTP 422/)
+    expect(response.result.content[0].text).toMatch(/99999/)
+  })
+})
diff --git a/src/main/control-server.ts b/src/main/control-server.ts
index 45ad6257..a27556d8 100644
--- a/src/main/control-server.ts
+++ b/src/main/control-server.ts
@@ -1,5 +1,5 @@
 import { createServer, IncomingMessage, ServerResponse } from 'http'
-import { randomBytes } from 'crypto'
+import { randomBytes, randomUUID } from 'crypto'
 import { addWorktree, listWorktrees, defaultWorktreeDir, WorktreeInfo } from './worktree'
 import { log } from './debug'
 
@@ -90,6 +90,16 @@ export interface ControlServerDeps {
   getWorktreeBase: () => 'remote' | 'local'
   broadcast: (channel: string, ...args: unknown[]) => void
   runWorktreeSetup: (ctx: { repoRoot: string; worktreePath: string; branch: string }) => Promise<void>
+  /** Drive the full PR-creation FSM (fetch PR metadata, fetch refs/pull/<n>/head,
+   * create the worktree, run setup, fire panes init + PR poller refresh) and
+   * return the new worktree's path + branch. Host wires this to
+   * `worktreesFSM.runPendingPR` plus a renderer focus broadcast. */
+  runPendingPRWorktree: (params: {
+    id: string
+    repoRoot: string
+    prNumber: number
+    initialPrompt?: string
+  }) => Promise<{ ok: true; path: string; branch: string } | { ok: false; error: string }>
   /** Returns the caller's current scope, or null if the terminal is not
    * associated with any known worktree (e.g. the worktree was deleted). */
   resolveCallerScope: (terminalId: string) => CallerScope | null
@@ -222,9 +232,38 @@ async function handleRequest(
       }
     }
 
+    const rawPrNumber = body.prNumber
+    let prNumber: number | undefined
+    if (rawPrNumber !== undefined && rawPrNumber !== null && rawPrNumber !== '') {
+      const n = typeof rawPrNumber === 'number' ? rawPrNumber : Number(rawPrNumber)
+      if (!Number.isInteger(n) || n <= 0) {
+        return sendJson(res, 400, { error: 'prNumber must be a positive integer' })
+      }
+      prNumber = n
+    }
+
     const branchName = String(body.branchName || '').trim()
+    const initialPrompt = typeof body.initialPrompt === 'string' ? body.initialPrompt : undefined
+
+    if (prNumber !== undefined) {
+      if (branchName) {
+        log('control', `prNumber=${prNumber} provided — ignoring branchName=${branchName}`)
+      }
+      const result = await deps.runPendingPRWorktree({
+        id: randomUUID(),
+        repoRoot,
+        prNumber,
+        initialPrompt
+      })
+      if (!result.ok) {
+        const status = /couldn't fetch pr|not found|404/i.test(result.error) ? 422 : 502
+        return sendJson(res, status, { error: result.error })
+      }
+      return sendJson(res, 200, { path: result.path, branch: result.branch })
+    }
+
     if (!branchName) {
-      return sendJson(res, 400, { error: 'branchName required' })
+      return sendJson(res, 400, { error: 'branchName or prNumber required' })
     }
     const wtDir = defaultWorktreeDir(repoRoot)
     const mode = deps.getWorktreeBase()
@@ -237,7 +276,6 @@ async function handleRequest(
     // spawned by ensureInitialized still sees shared settings.
     deps.runWorktreeSetup({ repoRoot, worktreePath: created.path, branch: created.branch })
       .catch((err) => log('control', `setup script failed: ${err instanceof Error ? err.message : String(err)}`))
-    const initialPrompt = typeof body.initialPrompt === 'string' ? body.initialPrompt : undefined
     deps.broadcast('worktrees:externalCreate', { repoRoot, worktree: created, initialPrompt })
     return sendJson(res, 200, created)
   }
diff --git a/src/main/index.ts b/src/main/index.ts
index 7dfa5f53..dd3ab2d3 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3087,6 +3087,31 @@ async function runBoot(): Promise<void> {
       }
     },
     runWorktreeSetup: (ctx) => worktreesFSM.runWorktreeSetup(ctx),
+    runPendingPRWorktree: async (params) => {
+      // The FSM already handles ensureInitialized (with the prompt) + PR poller
+      // refresh via onWorktreeCreated. We just look up the resolved branch
+      // from the freshly-refreshed store list and emit the focus broadcast
+      // directly so the heavy ensureInitialized/refreshList work doesn't
+      // run a second time through the broadcast path.
+      // 'setup-failed' still means the worktree exists on disk — surface
+      // it to the MCP caller as success so the agent can recover.
+      const outcome = await worktreesFSM.runPendingPR(params)
+      if (outcome.outcome === 'error') {
+        return { ok: false, error: outcome.error }
+      }
+      const found = store
+        .getSnapshot()
+        .state.worktrees.list.find((w) => w.path === outcome.createdPath)
+      if (!found) {
+        return { ok: false, error: `created worktree at ${outcome.createdPath} but couldn't resolve its branch` }
+      }
+      broadcastToAllWindows('worktrees:externalCreate', {
+        repoRoot: params.repoRoot,
+        worktree: found,
+        initialPrompt: params.initialPrompt
+      })
+      return { ok: true, path: found.path, branch: found.branch }
+    },
     broadcast: (channel, payload) => {
       if (channel === 'worktrees:externalCreate') {
         // Seed panes with the initial prompt BEFORE refreshList — the
diff --git a/src/main/worktrees-fsm.ts b/src/main/worktrees-fsm.ts
index 3726aa7a..68df9d8f 100644
--- a/src/main/worktrees-fsm.ts
+++ b/src/main/worktrees-fsm.ts
@@ -154,15 +154,17 @@ export class WorktreesFSM {
     id: string
     repoRoot: string
     prNumber: number
+    initialPrompt?: string
   }): Promise<PendingOutcome> {
-    const { id, repoRoot, prNumber } = params
+    const { id, repoRoot, prNumber, initialPrompt } = params
     // Show *something* while we go ask GitHub for the head ref name.
     let branchName = `pr-${prNumber}`
     const pending: PendingWorktree = {
       id,
       repoRoot,
       branchName,
-      status: 'creating'
+      status: 'creating',
+      initialPrompt
     }
     this.store.dispatch({ type: 'worktrees/pendingAdded', payload: pending })
 
@@ -188,7 +190,8 @@ export class WorktreesFSM {
       return await this.finishCreate({
         id,
         repoRoot,
-        created
+        created,
+        initialPrompt
       })
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err)

From 170b9fa532d6fcb43279ef6d7dd22cff0824e190 Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Fri, 22 May 2026 22:14:10 -0600
Subject: [PATCH 2/7] feat: configurable PR review prompt with per-creation
 textarea
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a `prReviewPrompt` setting (default ships with a sensible review
prompt) and exposes it three ways:

- Settings → Worktrees → PR review prompt: textarea + save/reset to
  manage the global default.
- New Worktree → Open PR section: textarea pre-filled with the default;
  edits are one-shot for that creation and don't affect the global value.
- MCP `create_worktree` with `prNumber`: an omitted `initialPrompt`
  falls back to the configured default. Pass an empty string to
  explicitly suppress.

Threading: extends `runPendingPR` (FSM) + `runPendingPRWorktree`
(renderer-facing backend method) with `initialPrompt?`, persists the
setting in `config.json`, seeds it through `buildInitialAppState`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 resources/mcp-bridge.js                       |  2 +-
 src/main/build-initial-state.ts               |  6 ++-
 src/main/control-server.ts                    | 10 +++-
 src/main/index.ts                             | 22 +++++++-
 src/main/persistence.ts                       |  3 ++
 src/renderer/build-backend.ts                 |  2 +
 src/renderer/components/NewWorktreeScreen.tsx | 45 ++++++++++++----
 src/renderer/components/Settings.tsx          | 54 +++++++++++++++++++
 src/renderer/hooks/useWorktreeHandlers.ts     |  5 +-
 src/renderer/types.ts                         |  2 +
 src/shared/state/settings.test.ts             |  9 ++++
 src/shared/state/settings.ts                  | 17 +++++-
 12 files changed, 158 insertions(+), 19 deletions(-)

diff --git a/resources/mcp-bridge.js b/resources/mcp-bridge.js
index fc537054..1703fcd2 100644
--- a/resources/mcp-bridge.js
+++ b/resources/mcp-bridge.js
@@ -103,7 +103,7 @@ const TOOLS = [
         initialPrompt: {
           type: 'string',
           description:
-            'A prompt to automatically send to the Claude chat tab when it opens in the new worktree. Useful for "review this PR for X" or "implement feature Y" prompts.'
+            'A prompt to automatically send to the Claude chat tab when it opens in the new worktree. Useful for "review this PR for X" or "implement feature Y" prompts. When prNumber is set and this is omitted, Harness uses the configured PR review prompt (Settings → Worktrees → PR review prompt). Pass an empty string to explicitly suppress any kickoff prompt on the PR path.'
         }
       }
     }
diff --git a/src/main/build-initial-state.ts b/src/main/build-initial-state.ts
index c657f21d..f8e2adc4 100644
--- a/src/main/build-initial-state.ts
+++ b/src/main/build-initial-state.ts
@@ -13,7 +13,8 @@ import { initialSnooze } from '../shared/state/snooze'
 import {
   initialSettings,
   DEFAULT_LIGHT_THEME,
-  DEFAULT_DARK_THEME
+  DEFAULT_DARK_THEME,
+  DEFAULT_PR_REVIEW_PROMPT
 } from '../shared/state/settings'
 import {
   DEFAULT_CLAUDE_COMMAND,
@@ -103,7 +104,8 @@ export function buildInitialAppState(
           ? Math.floor(config.autoSleepMinutes)
           : 30,
       snoozeDefaultDays: Math.max(1, Math.floor(config.snoozeDefaultDays ?? 7)),
-      expandedDiagnosticLoggingEnabled: config.expandedDiagnosticLoggingEnabled === true
+      expandedDiagnosticLoggingEnabled: config.expandedDiagnosticLoggingEnabled === true,
+      prReviewPrompt: config.prReviewPrompt || DEFAULT_PR_REVIEW_PROMPT
     }
   }
 }
diff --git a/src/main/control-server.ts b/src/main/control-server.ts
index a27556d8..56681675 100644
--- a/src/main/control-server.ts
+++ b/src/main/control-server.ts
@@ -88,6 +88,10 @@ export interface BrowserPerms {
 export interface ControlServerDeps {
   getRepoRoots: () => string[]
   getWorktreeBase: () => 'remote' | 'local'
+  /** Default prompt used when an MCP `create_worktree` call provides
+   * `prNumber` but no explicit `initialPrompt`. Resolved per-request so
+   * Settings edits take effect mid-session. */
+  getPrReviewPrompt: () => string
   broadcast: (channel: string, ...args: unknown[]) => void
   runWorktreeSetup: (ctx: { repoRoot: string; worktreePath: string; branch: string }) => Promise<void>
   /** Drive the full PR-creation FSM (fetch PR metadata, fetch refs/pull/<n>/head,
@@ -249,11 +253,15 @@ async function handleRequest(
       if (branchName) {
         log('control', `prNumber=${prNumber} provided — ignoring branchName=${branchName}`)
       }
+      // No explicit prompt → fall back to the configured review-prompt default.
+      // Empty-string prompts ('') are honored as "no prompt" so callers can
+      // opt out explicitly.
+      const promptForPR = initialPrompt === undefined ? deps.getPrReviewPrompt() : initialPrompt
       const result = await deps.runPendingPRWorktree({
         id: randomUUID(),
         repoRoot,
         prNumber,
-        initialPrompt
+        initialPrompt: promptForPR || undefined
       })
       if (!result.ok) {
         const status = /couldn't fetch pr|not found|404/i.test(result.error) ? 422 : 502
diff --git a/src/main/index.ts b/src/main/index.ts
index dd3ab2d3..02892e68 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -68,7 +68,11 @@ import { registerRepoRoot } from './repo-roots'
 import type { AddRepoResult } from '../shared/repo-pick'
 import { isWorktreeMerged } from '../shared/state/prs'
 import { MAX_WAKE } from '../shared/state/snooze'
-import { DEFAULT_LIGHT_THEME, DEFAULT_DARK_THEME } from '../shared/state/settings'
+import {
+  DEFAULT_LIGHT_THEME,
+  DEFAULT_DARK_THEME,
+  DEFAULT_PR_REVIEW_PROMPT
+} from '../shared/state/settings'
 import { watchStatusDir } from './hooks'
 import { getAgent, type AgentKind } from './agents'
 import { buildClaudeLaunchSettings } from './claude-launch'
@@ -1576,6 +1580,21 @@ function registerIpcHandlers(): void {
     return true
   })
 
+  transport.onRequest('config:setPrReviewPrompt', (_ctx, prompt: string) => {
+    const trimmed = prompt.trim()
+    if (!trimmed || trimmed === DEFAULT_PR_REVIEW_PROMPT) {
+      delete config.prReviewPrompt
+    } else {
+      config.prReviewPrompt = prompt
+    }
+    saveConfig(config)
+    store.dispatch({
+      type: 'settings/prReviewPromptChanged',
+      payload: config.prReviewPrompt || DEFAULT_PR_REVIEW_PROMPT
+    })
+    return true
+  })
+
   transport.onRequest('config:setHarnessMcpEnabled', (_ctx, enabled: boolean) => {
     if (enabled) {
       delete config.harnessMcpEnabled
@@ -2949,6 +2968,7 @@ async function runBoot(): Promise<void> {
   startControlServer({
     getRepoRoots: () => config.repoRoots,
     getWorktreeBase: () => config.worktreeBase || DEFAULT_WORKTREE_BASE,
+    getPrReviewPrompt: () => config.prReviewPrompt || DEFAULT_PR_REVIEW_PROMPT,
     resolveCallerScope,
     getBrowserPerms: () => ({
       enabled: config.browserToolsEnabled !== false,
diff --git a/src/main/persistence.ts b/src/main/persistence.ts
index 32220712..fe998208 100644
--- a/src/main/persistence.ts
+++ b/src/main/persistence.ts
@@ -151,6 +151,9 @@ export interface Config {
   harnessSystemPromptEnabled?: boolean
   harnessSystemPrompt?: string
   harnessSystemPromptMain?: string
+  // Default kickoff prompt for "Open PR as worktree" / MCP create_worktree
+  // with prNumber. Absent = use the bundled DEFAULT_PR_REVIEW_PROMPT.
+  prReviewPrompt?: string
   // When false, Claude sessions spawn without CLAUDE_CODE_NO_FLICKER=1, so they
   // use the inline (non-fullscreen) TUI mode. Default is enabled (undefined/true).
   claudeTuiFullscreen?: boolean
diff --git a/src/renderer/build-backend.ts b/src/renderer/build-backend.ts
index 1e7e38a4..6e84c898 100644
--- a/src/renderer/build-backend.ts
+++ b/src/renderer/build-backend.ts
@@ -106,6 +106,7 @@ export function buildBackend(
       id: string
       repoRoot: string
       prNumber: number
+      initialPrompt?: string
     }) => req('worktrees:runPendingPR', params),
     retryPendingWorktree: (id: string) => req('worktrees:retryPending', id),
     dismissPendingWorktree: (id: string) => req('worktrees:dismissPending', id),
@@ -247,6 +248,7 @@ export function buildBackend(
     setHarnessSystemPrompt: (prompt: string) => req('config:setHarnessSystemPrompt', prompt),
     setHarnessSystemPromptMain: (prompt: string) =>
       req('config:setHarnessSystemPromptMain', prompt),
+    setPrReviewPrompt: (prompt: string) => req('config:setPrReviewPrompt', prompt),
     prepareMcpForTerminal: (terminalId: string) =>
       req('mcp:prepareForTerminal', terminalId),
     onWorktreesExternalCreate: (
diff --git a/src/renderer/components/NewWorktreeScreen.tsx b/src/renderer/components/NewWorktreeScreen.tsx
index 1fc6a597..2beb10a4 100644
--- a/src/renderer/components/NewWorktreeScreen.tsx
+++ b/src/renderer/components/NewWorktreeScreen.tsx
@@ -4,11 +4,12 @@ import iconUrl from '../../../resources/icon.png'
 import { sanitizeBranchInput, isValidBranchName } from '../branch-name'
 import { RepoIcon } from './RepoIcon'
 import { useBackend } from '../backend'
+import { useSettings } from '../store'
 import type { PRSummary } from '../types'
 
 interface NewWorktreeScreenProps {
   onSubmit: (repoRoot: string, branchName: string, initialPrompt: string, teleportSessionId?: string) => Promise<void>
-  onPRSubmit: (repoRoot: string, prNumber: number) => Promise<void>
+  onPRSubmit: (repoRoot: string, prNumber: number, initialPrompt: string) => Promise<void>
   onCancel: () => void
   repoRoots: string[]
   /** Repo to pre-select in the picker. Usually the repo of the currently active worktree. */
@@ -76,6 +77,8 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
   )
   const [branch, setBranch] = useState('')
   const [prompt, setPrompt] = useState('')
+  const settings = useSettings()
+  const [reviewPrompt, setReviewPrompt] = useState(settings.prReviewPrompt)
   const [teleportInput, setTeleportInput] = useState('')
   const [submitting, setSubmitting] = useState(false)
   const [error, setError] = useState<string | null>(null)
@@ -143,13 +146,13 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
       setPrClickPending(prNumber)
       setError(null)
       try {
-        await onPRSubmit(selectedRepo, prNumber)
+        await onPRSubmit(selectedRepo, prNumber, reviewPrompt.trim())
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to open PR')
         setPrClickPending(null)
       }
     },
-    [onPRSubmit, prClickPending, selectedRepo]
+    [onPRSubmit, prClickPending, selectedRepo, reviewPrompt]
   )
 
   const handleBranchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
@@ -402,14 +405,34 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
             )}
 
             {mode === 'pr' && (
-              <PRPickerList
-                prs={prsByRepo[selectedRepo]}
-                loading={prsLoadingRepo === selectedRepo}
-                error={prsError}
-                disabled={prClickPending !== null}
-                pendingNumber={prClickPending}
-                onPick={handlePRClick}
-              />
+              <>
+                <label className="block mb-4">
+                  <div className="flex items-center justify-between mb-2">
+                    <span className="text-[11px] font-semibold uppercase tracking-wider text-dim">
+                      Review prompt
+                    </span>
+                    <span className="text-[11px] text-faint">
+                      sent to Claude after the PR loads · edit defaults in Settings
+                    </span>
+                  </div>
+                  <textarea
+                    value={reviewPrompt}
+                    onChange={(e) => setReviewPrompt(e.target.value)}
+                    placeholder="Leave blank to drop in with no kickoff prompt."
+                    disabled={prClickPending !== null}
+                    rows={4}
+                    className="w-full bg-app border-2 border-border-strong rounded-lg px-4 py-3 text-sm text-fg-bright placeholder-faint outline-none focus:border-accent transition-colors resize-none"
+                  />
+                </label>
+                <PRPickerList
+                  prs={prsByRepo[selectedRepo]}
+                  loading={prsLoadingRepo === selectedRepo}
+                  error={prsError}
+                  disabled={prClickPending !== null}
+                  pendingNumber={prClickPending}
+                  onPick={handlePRClick}
+                />
+              </>
             )}
 
             {error && (
diff --git a/src/renderer/components/Settings.tsx b/src/renderer/components/Settings.tsx
index 4dc1944d..8ab3fcb3 100644
--- a/src/renderer/components/Settings.tsx
+++ b/src/renderer/components/Settings.tsx
@@ -189,6 +189,7 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
     harnessSystemPromptEnabled,
     harnessSystemPrompt,
     harnessSystemPromptMain,
+    prReviewPrompt,
     claudeTuiFullscreen,
     browserToolsEnabled,
     browserToolsMode,
@@ -252,6 +253,10 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
   useEffect(() => { setSystemPromptMainDraft(harnessSystemPromptMain) }, [harnessSystemPromptMain])
   const [systemPromptSaveResult, setSystemPromptSaveResult] = useState<{ ok: boolean; message: string } | null>(null)
 
+  const [prReviewPromptDraft, setPrReviewPromptDraft] = useState<string>(prReviewPrompt)
+  useEffect(() => { setPrReviewPromptDraft(prReviewPrompt) }, [prReviewPrompt])
+  const [prReviewPromptSaveResult, setPrReviewPromptSaveResult] = useState<{ ok: boolean; message: string } | null>(null)
+
   const [defaultTerminalFontFamily, setDefaultTerminalFontFamily] = useState<string>('')
   const [availableEditors, setAvailableEditors] = useState<{ id: string; name: string }[]>([])
   const [scriptsSaveResult, setScriptsSaveResult] = useState<{ ok: boolean; message: string } | null>(null)
@@ -666,6 +671,18 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
     setTimeout(() => setSystemPromptSaveResult(null), 2000)
   }, [])
 
+  const handleSavePrReviewPrompt = useCallback(async () => {
+    await backend.setPrReviewPrompt(prReviewPromptDraft)
+    setPrReviewPromptSaveResult({ ok: true, message: 'Saved' })
+    setTimeout(() => setPrReviewPromptSaveResult(null), 2000)
+  }, [prReviewPromptDraft])
+
+  const handleResetPrReviewPrompt = useCallback(async () => {
+    await backend.setPrReviewPrompt('')
+    setPrReviewPromptSaveResult({ ok: true, message: 'Reset to default' })
+    setTimeout(() => setPrReviewPromptSaveResult(null), 2000)
+  }, [])
+
   const effectiveClaudeCommand = claudeCommandDraft.trim() || defaultClaudeCommand
   const modelPart = claudeModel && !effectiveClaudeCommand.includes('--model') ? ` --model ${claudeModel}` : ''
   const mcpPart = harnessMcpEnabled ? ' --mcp-config <per-session>' : ''
@@ -1586,6 +1603,43 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
                 Controls how new worktrees are created from the sidebar.
               </p>
 
+              <h3 className="text-sm font-semibold text-fg-bright mb-3">PR review prompt</h3>
+              <div className="bg-panel-raised border border-border rounded-lg p-4 mb-6">
+                <p className="text-xs text-dim mb-2">
+                  Default kickoff prompt sent to Claude when you open a PR as a worktree (or when the MCP{' '}
+                  <code className="bg-panel px-1 rounded text-[10px]">create_worktree</code> tool is invoked with{' '}
+                  <code className="bg-panel px-1 rounded text-[10px]">prNumber</code> and no explicit prompt). You can
+                  edit the prompt per-PR from the New Worktree screen.
+                </p>
+                <textarea
+                  value={prReviewPromptDraft}
+                  onChange={(e) => setPrReviewPromptDraft(e.target.value)}
+                  rows={5}
+                  spellCheck={false}
+                  className="w-full bg-panel border border-border-strong rounded px-3 py-2 text-xs text-fg-bright placeholder-faint outline-none focus:border-fg font-mono resize-y"
+                />
+                <div className="flex items-center gap-2 mt-3">
+                  <button
+                    onClick={handleSavePrReviewPrompt}
+                    className="px-3 py-1.5 bg-surface hover:bg-surface-hover rounded text-sm text-fg-bright transition-colors cursor-pointer"
+                  >
+                    Save
+                  </button>
+                  <button
+                    onClick={handleResetPrReviewPrompt}
+                    className="flex items-center gap-1 px-3 py-1.5 text-sm text-dim hover:text-fg transition-colors cursor-pointer"
+                  >
+                    <RotateCcw size={12} />
+                    Reset to default
+                  </button>
+                </div>
+                {prReviewPromptSaveResult && (
+                  <div className={`mt-3 text-xs flex items-center gap-1.5 ${prReviewPromptSaveResult.ok ? 'text-success' : 'text-danger'}`}>
+                    {prReviewPromptSaveResult.ok ? <Check size={12} /> : <X size={12} />}{prReviewPromptSaveResult.message}
+                  </div>
+                )}
+              </div>
+
               {repoList.length > 0 && (
                 <div className="mb-4">
                   <div className="flex items-center gap-1 text-[11px] text-faint mb-1.5 uppercase tracking-wide">
diff --git a/src/renderer/hooks/useWorktreeHandlers.ts b/src/renderer/hooks/useWorktreeHandlers.ts
index 64dbcb85..e8219771 100644
--- a/src/renderer/hooks/useWorktreeHandlers.ts
+++ b/src/renderer/hooks/useWorktreeHandlers.ts
@@ -188,7 +188,7 @@ export function useWorktreeHandlers(args: UseWorktreeHandlersArgs) {
   )
 
   const handleSubmitNewPRWorktree = useCallback(
-    async (repoRoot: string, prNumber: number) => {
+    async (repoRoot: string, prNumber: number, initialPrompt: string) => {
       const id = `pending:${crypto.randomUUID()}`
       setActiveWorktreeId(id)
       setShowNewWorktree(false)
@@ -196,7 +196,8 @@ export function useWorktreeHandlers(args: UseWorktreeHandlersArgs) {
       const result = await backend.runPendingPRWorktree({
         id,
         repoRoot,
-        prNumber
+        prNumber,
+        initialPrompt: initialPrompt || undefined
       })
 
       if (result.outcome === 'success') {
diff --git a/src/renderer/types.ts b/src/renderer/types.ts
index ce649bea..3c867e43 100644
--- a/src/renderer/types.ts
+++ b/src/renderer/types.ts
@@ -178,6 +178,7 @@ export interface ElectronAPI {
     id: string
     repoRoot: string
     prNumber: number
+    initialPrompt?: string
   }): Promise<
     | { id: string; outcome: 'success'; createdPath: string }
     | { id: string; outcome: 'setup-failed'; createdPath: string }
@@ -303,6 +304,7 @@ export interface ElectronAPI {
   setHarnessSystemPromptEnabled(enabled: boolean): Promise<boolean>
   setHarnessSystemPrompt(prompt: string): Promise<boolean>
   setHarnessSystemPromptMain(prompt: string): Promise<boolean>
+  setPrReviewPrompt(prompt: string): Promise<boolean>
   prepareMcpForTerminal(terminalId: string): Promise<string | null>
   onWorktreesExternalCreate(
     callback: (payload: { repoRoot: string; worktree: Worktree; initialPrompt?: string }) => void
diff --git a/src/shared/state/settings.test.ts b/src/shared/state/settings.test.ts
index 1e1c9de0..ac2f8751 100644
--- a/src/shared/state/settings.test.ts
+++ b/src/shared/state/settings.test.ts
@@ -103,6 +103,15 @@ describe('settingsReducer', () => {
     expect(off.expandedDiagnosticLoggingEnabled).toBe(false)
   })
 
+  it('prReviewPromptChanged overrides the default review prompt', () => {
+    expect(initialSettings.prReviewPrompt.length).toBeGreaterThan(0)
+    const next = apply(initialSettings, {
+      type: 'settings/prReviewPromptChanged',
+      payload: 'Focus on security issues only.'
+    })
+    expect(next.prReviewPrompt).toBe('Focus on security issues only.')
+  })
+
   it('autoUpdateEnabledChanged toggles auto-update flag', () => {
     expect(initialSettings.autoUpdateEnabled).toBe(true)
     const off = apply(initialSettings, {
diff --git a/src/shared/state/settings.ts b/src/shared/state/settings.ts
index eb0b3aa0..b35f3d56 100644
--- a/src/shared/state/settings.ts
+++ b/src/shared/state/settings.ts
@@ -46,6 +46,11 @@ export const EMPTY_CUSTOM_THEMES: CustomTheme[] = []
 export const DEFAULT_LIGHT_THEME = 'solarized-light'
 export const DEFAULT_DARK_THEME = 'dark'
 
+/** Default kickoff prompt for "Open PR as worktree". Editable globally in
+ *  Settings (`prReviewPrompt`) and per-creation in the New Worktree screen. */
+export const DEFAULT_PR_REVIEW_PROMPT =
+  "Review this PR. Read the diff, then check for correctness issues, design problems, security concerns, and missing edge cases. Cite file paths and line numbers for anything you flag. Skip restating what the PR does — focus on what could go wrong or be improved."
+
 export interface SettingsState {
   /** Whether the active theme is the light theme, the dark theme, or follows
    *  the OS appearance. Default 'system'. */
@@ -141,6 +146,12 @@ export interface SettingsState {
    *  volume is high during PR refresh bursts. HUD metrics like "GH API"
    *  rate are always on regardless of this flag. */
   expandedDiagnosticLoggingEnabled: boolean
+  /** Default prompt pre-filled into the "Open PR as worktree" screen and
+   *  used as the kickoff prompt when an MCP `create_worktree` call provides
+   *  a `prNumber` without an explicit `initialPrompt`. The textarea on the
+   *  PR-creation screen is seeded from this value but edits there are
+   *  one-shot — managing the default happens in Settings. */
+  prReviewPrompt: string
 }
 
 export type SettingsEvent =
@@ -192,6 +203,7 @@ export type SettingsEvent =
   | { type: 'settings/autoSleepMinutesChanged'; payload: number }
   | { type: 'settings/snoozeDefaultDaysChanged'; payload: number }
   | { type: 'settings/expandedDiagnosticLoggingEnabledChanged'; payload: boolean }
+  | { type: 'settings/prReviewPromptChanged'; payload: string }
 
 // Client-side placeholder. Real values are seeded in the main-process Store
 // constructor from the on-disk config and secrets.
@@ -240,7 +252,8 @@ export const initialSettings: SettingsState = {
   jsonModeDefaultPermissionMode: 'acceptEdits',
   autoSleepMinutes: 30,
   snoozeDefaultDays: 7,
-  expandedDiagnosticLoggingEnabled: false
+  expandedDiagnosticLoggingEnabled: false,
+  prReviewPrompt: DEFAULT_PR_REVIEW_PROMPT
 }
 
 export function settingsReducer(state: SettingsState, event: SettingsEvent): SettingsState {
@@ -335,6 +348,8 @@ export function settingsReducer(state: SettingsState, event: SettingsEvent): Set
       return { ...state, snoozeDefaultDays: event.payload }
     case 'settings/expandedDiagnosticLoggingEnabledChanged':
       return { ...state, expandedDiagnosticLoggingEnabled: event.payload }
+    case 'settings/prReviewPromptChanged':
+      return { ...state, prReviewPrompt: event.payload }
     default: {
       const _exhaustive: never = event
       void _exhaustive

From 497013e68d82aa4b68cefb1bab4ce9dd7ea6cd84 Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Fri, 22 May 2026 22:35:13 -0600
Subject: [PATCH 3/7] move PR review prompt below other Worktrees defaults
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tucks the textarea in next to "Share Claude Code permissions" — both
are global "default behavior" settings most users won't touch, so the
section now leads with the per-creation knobs (merge strategy, scripts)
and ends with the defaults.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/renderer/components/Settings.tsx | 72 ++++++++++++++--------------
 1 file changed, 35 insertions(+), 37 deletions(-)

diff --git a/src/renderer/components/Settings.tsx b/src/renderer/components/Settings.tsx
index 8ab3fcb3..5be1f053 100644
--- a/src/renderer/components/Settings.tsx
+++ b/src/renderer/components/Settings.tsx
@@ -1603,43 +1603,6 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
                 Controls how new worktrees are created from the sidebar.
               </p>
 
-              <h3 className="text-sm font-semibold text-fg-bright mb-3">PR review prompt</h3>
-              <div className="bg-panel-raised border border-border rounded-lg p-4 mb-6">
-                <p className="text-xs text-dim mb-2">
-                  Default kickoff prompt sent to Claude when you open a PR as a worktree (or when the MCP{' '}
-                  <code className="bg-panel px-1 rounded text-[10px]">create_worktree</code> tool is invoked with{' '}
-                  <code className="bg-panel px-1 rounded text-[10px]">prNumber</code> and no explicit prompt). You can
-                  edit the prompt per-PR from the New Worktree screen.
-                </p>
-                <textarea
-                  value={prReviewPromptDraft}
-                  onChange={(e) => setPrReviewPromptDraft(e.target.value)}
-                  rows={5}
-                  spellCheck={false}
-                  className="w-full bg-panel border border-border-strong rounded px-3 py-2 text-xs text-fg-bright placeholder-faint outline-none focus:border-fg font-mono resize-y"
-                />
-                <div className="flex items-center gap-2 mt-3">
-                  <button
-                    onClick={handleSavePrReviewPrompt}
-                    className="px-3 py-1.5 bg-surface hover:bg-surface-hover rounded text-sm text-fg-bright transition-colors cursor-pointer"
-                  >
-                    Save
-                  </button>
-                  <button
-                    onClick={handleResetPrReviewPrompt}
-                    className="flex items-center gap-1 px-3 py-1.5 text-sm text-dim hover:text-fg transition-colors cursor-pointer"
-                  >
-                    <RotateCcw size={12} />
-                    Reset to default
-                  </button>
-                </div>
-                {prReviewPromptSaveResult && (
-                  <div className={`mt-3 text-xs flex items-center gap-1.5 ${prReviewPromptSaveResult.ok ? 'text-success' : 'text-danger'}`}>
-                    {prReviewPromptSaveResult.ok ? <Check size={12} /> : <X size={12} />}{prReviewPromptSaveResult.message}
-                  </div>
-                )}
-              </div>
-
               {repoList.length > 0 && (
                 <div className="mb-4">
                   <div className="flex items-center gap-1 text-[11px] text-faint mb-1.5 uppercase tracking-wide">
@@ -1920,6 +1883,41 @@ export function Settings({ onClose, onOpenGuide, onOpenMyWeek, initialSection }:
                       Share settings.local.json across worktrees
                     </span>
                   </label>
+
+                  <h3 className="text-sm font-semibold text-fg-bright mt-6 mb-1">PR review prompt</h3>
+                  <p className="text-xs text-dim mb-3">
+                    Default kickoff prompt sent to Claude when you open a PR as a worktree (or when the MCP{' '}
+                    <code className="bg-panel-raised px-1 rounded text-[10px]">create_worktree</code> tool is invoked
+                    with <code className="bg-panel-raised px-1 rounded text-[10px]">prNumber</code> and no explicit
+                    prompt). You can edit the prompt per-PR from the New Worktree screen.
+                  </p>
+                  <textarea
+                    value={prReviewPromptDraft}
+                    onChange={(e) => setPrReviewPromptDraft(e.target.value)}
+                    rows={5}
+                    spellCheck={false}
+                    className="w-full bg-panel border border-border-strong rounded px-3 py-2 text-xs text-fg-bright placeholder-faint outline-none focus:border-fg font-mono resize-y"
+                  />
+                  <div className="flex items-center gap-2 mt-3">
+                    <button
+                      onClick={handleSavePrReviewPrompt}
+                      className="px-3 py-1.5 bg-surface hover:bg-surface-hover rounded text-sm text-fg-bright transition-colors cursor-pointer"
+                    >
+                      Save
+                    </button>
+                    <button
+                      onClick={handleResetPrReviewPrompt}
+                      className="flex items-center gap-1 px-3 py-1.5 text-sm text-dim hover:text-fg transition-colors cursor-pointer"
+                    >
+                      <RotateCcw size={12} />
+                      Reset to default
+                    </button>
+                  </div>
+                  {prReviewPromptSaveResult && (
+                    <div className={`mt-3 text-xs flex items-center gap-1.5 ${prReviewPromptSaveResult.ok ? 'text-success' : 'text-danger'}`}>
+                      {prReviewPromptSaveResult.ok ? <Check size={12} /> : <X size={12} />}{prReviewPromptSaveResult.message}
+                    </div>
+                  )}
                 </>
               )}
 

From f1e1f5e073e2bb0131729592d7fc25889b6b9a6c Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Mon, 25 May 2026 08:48:48 -0600
Subject: [PATCH 4/7] feat: per-creation agent + model overrides (New Worktree
 UI + MCP)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes #74.

A worktree's first agent tab now picks up two overrides set at creation
time:

- **agentKind**: claude or codex. Defaults to settings.defaultAgent.
- **model**: free-text string passed as --model. Defaults to
  settings.claudeModel / settings.codexModel.

Both surface through:

- **New Worktree screen** — a compact "Agent / Model" row sits under
  the per-mode input area. Teleport mode pins to Claude since codex
  has no resume-by-session-id analog today.
- **MCP create_worktree** — new `agentKind` and `model` params.
  Both validated server-side; agentKind must be claude|codex.

Persistence: model lives on TerminalTab as a new optional field so it
survives reload — agent:buildSpawnArgs honors tab.model over settings,
and the json-claude path threads the override through
buildClaudeLaunchSettings → --model.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 resources/mcp-bridge.js                       |  33 ++++-
 resources/mcp-bridge.test.js                  |  61 ++++++++
 src/main/claude-launch.test.ts                |  29 ++++
 src/main/claude-launch.ts                     |   8 +-
 src/main/control-server.ts                    |  24 ++-
 src/main/index.ts                             |  60 ++++++--
 src/main/json-claude-manager.ts               |   9 +-
 src/main/panes-fsm.ts                         |  23 ++-
 src/main/worktrees-fsm.ts                     |  28 +++-
 src/renderer/build-backend.ts                 |   5 +
 src/renderer/components/MobileTerminal.tsx    |   1 +
 src/renderer/components/NewWorktreeScreen.tsx | 139 +++++++++++++++++-
 src/renderer/components/WorkspaceView.tsx     |   1 +
 src/renderer/components/XTerminal.tsx         |   8 +-
 src/renderer/hooks/useWorktreeHandlers.ts     |  22 ++-
 src/renderer/types.ts                         |   6 +-
 src/shared/state/terminals.ts                 |   5 +
 17 files changed, 414 insertions(+), 48 deletions(-)

diff --git a/resources/mcp-bridge.js b/resources/mcp-bridge.js
index 1703fcd2..67186989 100644
--- a/resources/mcp-bridge.js
+++ b/resources/mcp-bridge.js
@@ -75,7 +75,7 @@ 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 Claude 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.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -103,7 +103,18 @@ const TOOLS = [
         initialPrompt: {
           type: 'string',
           description:
-            'A prompt to automatically send to the Claude chat tab when it opens in the new worktree. Useful for "review this PR for X" or "implement feature Y" prompts. When prNumber is set and this is omitted, Harness uses the configured PR review prompt (Settings → Worktrees → PR review prompt). Pass an empty string to explicitly suppress any kickoff prompt on the PR path.'
+            'A prompt to automatically send to the agent chat tab when it opens in the new worktree. Useful for "review this PR for X" or "implement feature Y" prompts. When prNumber is set and this is omitted, Harness uses the configured PR review prompt (Settings → Worktrees → PR review prompt). Pass an empty string to explicitly suppress any kickoff prompt on the PR path.'
+        },
+        agentKind: {
+          type: 'string',
+          enum: ['claude', 'codex'],
+          description:
+            "Which CLI agent to spawn in the new worktree's first tab. Defaults to the user's configured default agent (Settings → Agent)."
+        },
+        model: {
+          type: 'string',
+          description:
+            "Model string to pass to the agent CLI's --model flag for this worktree's first tab (e.g. 'opus', 'sonnet-4-5', 'gpt-5'). Pinned per-tab — survives reloads, doesn't affect other worktrees. Omit to use the global default (Settings → Agent)."
         }
       }
     }
@@ -453,17 +464,29 @@ async function handleToolCall(name, args) {
         throw new Error('prNumber must be a positive integer')
       }
     }
+    if (
+      args.agentKind !== undefined &&
+      args.agentKind !== null &&
+      args.agentKind !== 'claude' &&
+      args.agentKind !== 'codex'
+    ) {
+      throw new Error('agentKind must be "claude" or "codex"')
+    }
     const r = await callControl('POST', '/worktrees', {
       terminalId: TERMINAL_ID,
       repoRoot: args.repoRoot,
       branchName: args.branchName,
       prNumber: prNumber,
       baseBranch: args.baseBranch,
-      initialPrompt: args.initialPrompt
+      initialPrompt: args.initialPrompt,
+      agentKind: args.agentKind,
+      model: args.model
     })
+    const agentLabel = args.agentKind === 'codex' ? 'Codex' : 'Claude'
+    const modelSuffix = args.model ? ` (model: ${args.model})` : ''
     return prNumber
-      ? `Created worktree ${r.path} on branch ${r.branch} for PR #${prNumber}. Harness will open a new Claude chat tab in it.`
-      : `Created worktree ${r.path} on branch ${r.branch}. Harness will open a new Claude chat tab in it.`
+      ? `Created worktree ${r.path} on branch ${r.branch} for PR #${prNumber}. Harness will open a new ${agentLabel} chat tab in it${modelSuffix}.`
+      : `Created worktree ${r.path} on branch ${r.branch}. Harness will open a new ${agentLabel} chat tab in it${modelSuffix}.`
   }
   if (name === 'list_worktrees') {
     const q =
diff --git a/resources/mcp-bridge.test.js b/resources/mcp-bridge.test.js
index 11dacc96..4e669e1a 100644
--- a/resources/mcp-bridge.test.js
+++ b/resources/mcp-bridge.test.js
@@ -214,6 +214,67 @@ describe('mcp-bridge create_worktree', () => {
     expect(postCall).toBeUndefined()
   })
 
+  it('forwards agentKind + model to POST /worktrees and reports them in result text', async () => {
+    stub = await startStub((req, body, res) => {
+      if (req.url === '/scope') {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        return res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ path: '/tmp/wt-codex', branch: 'feat' }))
+    })
+    bridge = spawnBridge(stub.port, 'tok')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: {
+        name: 'create_worktree',
+        arguments: { branchName: 'feat', agentKind: 'codex', model: 'gpt-5' }
+      }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBeFalsy()
+    const text = response.result.content[0].text
+    expect(text).toContain('Codex')
+    expect(text).toContain('gpt-5')
+
+    const postCall = stub.captured.find((c) => c.method === 'POST' && c.url === '/worktrees')
+    expect(postCall).toBeDefined()
+    expect(postCall.body.agentKind).toBe('codex')
+    expect(postCall.body.model).toBe('gpt-5')
+  })
+
+  it('rejects unknown agentKind locally without hitting the server', async () => {
+    stub = await startStub((req, body, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end(JSON.stringify({ scope: null, browser: { enabled: true, mode: 'full' } }))
+    })
+    bridge = spawnBridge(stub.port, 'tok')
+
+    bridge.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+    await bridge.next()
+    bridge.send({
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/call',
+      params: {
+        name: 'create_worktree',
+        arguments: { branchName: 'feat', agentKind: 'gemini' }
+      }
+    })
+    const response = await bridge.next()
+
+    expect(response.result.isError).toBe(true)
+    expect(response.result.content[0].text).toMatch(/claude.*codex/i)
+    const postCall = stub.captured.find((c) => c.method === 'POST' && c.url === '/worktrees')
+    expect(postCall).toBeUndefined()
+  })
+
   it('surfaces server-side PR failures back to the caller', async () => {
     stub = await startStub((req, body, res) => {
       if (req.url === '/scope') {
diff --git a/src/main/claude-launch.test.ts b/src/main/claude-launch.test.ts
index 00d018cf..aa9be348 100644
--- a/src/main/claude-launch.test.ts
+++ b/src/main/claude-launch.test.ts
@@ -93,6 +93,35 @@ describe('buildClaudeLaunchSettings', () => {
     ).toBeUndefined()
   })
 
+  it('modelOverride wins over claudeModel and trims whitespace', () => {
+    const wt = makeWorktree()
+    expect(
+      buildClaudeLaunchSettings({
+        cwd: wt.path,
+        worktrees: [wt],
+        config: { claudeModel: 'opus' },
+        modelOverride: 'sonnet-4-5'
+      }).model
+    ).toBe('sonnet-4-5')
+    expect(
+      buildClaudeLaunchSettings({
+        cwd: wt.path,
+        worktrees: [wt],
+        config: {},
+        modelOverride: '  haiku  '
+      }).model
+    ).toBe('haiku')
+    // Blank/whitespace override falls through to settings.
+    expect(
+      buildClaudeLaunchSettings({
+        cwd: wt.path,
+        worktrees: [wt],
+        config: { claudeModel: 'opus' },
+        modelOverride: '   '
+      }).model
+    ).toBe('opus')
+  })
+
   it('builds sessionName from repoLabel/branch when nameClaudeSessions is on', () => {
     const wt = makeWorktree({ repoRoot: '/Users/x/code/myrepo', branch: 'feat-x' })
     const out = buildClaudeLaunchSettings({
diff --git a/src/main/claude-launch.ts b/src/main/claude-launch.ts
index a4aa5dd8..f85a869d 100644
--- a/src/main/claude-launch.ts
+++ b/src/main/claude-launch.ts
@@ -28,8 +28,11 @@ export function buildClaudeLaunchSettings(input: {
   cwd: string
   worktrees: Worktree[]
   config: ClaudeLaunchConfig
+  /** Per-tab model override. When set (and non-empty after trim), wins
+   *  over `config.claudeModel`. */
+  modelOverride?: string
 }): ClaudeLaunchSettings {
-  const { cwd, worktrees, config } = input
+  const { cwd, worktrees, config, modelOverride } = input
   const wt = worktrees.find((w) => w.path === cwd)
   const isMain = wt?.isMain ?? false
 
@@ -46,7 +49,8 @@ export function buildClaudeLaunchSettings(input: {
     if (!systemPrompt.trim()) systemPrompt = undefined
   }
 
-  const model = config.claudeModel ? config.claudeModel : undefined
+  const override = modelOverride && modelOverride.trim() ? modelOverride.trim() : undefined
+  const model = override || (config.claudeModel ? config.claudeModel : undefined)
 
   let sessionName: string | undefined
   if (config.nameClaudeSessions && wt) {
diff --git a/src/main/control-server.ts b/src/main/control-server.ts
index 56681675..515f32a7 100644
--- a/src/main/control-server.ts
+++ b/src/main/control-server.ts
@@ -103,6 +103,8 @@ export interface ControlServerDeps {
     repoRoot: string
     prNumber: number
     initialPrompt?: string
+    agentKind?: 'claude' | 'codex'
+    model?: string
   }) => Promise<{ ok: true; path: string; branch: string } | { ok: false; error: string }>
   /** Returns the caller's current scope, or null if the terminal is not
    * associated with any known worktree (e.g. the worktree was deleted). */
@@ -249,6 +251,16 @@ async function handleRequest(
     const branchName = String(body.branchName || '').trim()
     const initialPrompt = typeof body.initialPrompt === 'string' ? body.initialPrompt : undefined
 
+    const rawAgent = typeof body.agentKind === 'string' ? body.agentKind.trim().toLowerCase() : ''
+    let agentKind: 'claude' | 'codex' | undefined
+    if (rawAgent) {
+      if (rawAgent !== 'claude' && rawAgent !== 'codex') {
+        return sendJson(res, 400, { error: 'agentKind must be "claude" or "codex"' })
+      }
+      agentKind = rawAgent
+    }
+    const model = typeof body.model === 'string' && body.model.trim() ? body.model.trim() : undefined
+
     if (prNumber !== undefined) {
       if (branchName) {
         log('control', `prNumber=${prNumber} provided — ignoring branchName=${branchName}`)
@@ -261,7 +273,9 @@ async function handleRequest(
         id: randomUUID(),
         repoRoot,
         prNumber,
-        initialPrompt: promptForPR || undefined
+        initialPrompt: promptForPR || undefined,
+        agentKind,
+        model
       })
       if (!result.ok) {
         const status = /couldn't fetch pr|not found|404/i.test(result.error) ? 422 : 502
@@ -284,7 +298,13 @@ async function handleRequest(
     // spawned by ensureInitialized still sees shared settings.
     deps.runWorktreeSetup({ repoRoot, worktreePath: created.path, branch: created.branch })
       .catch((err) => log('control', `setup script failed: ${err instanceof Error ? err.message : String(err)}`))
-    deps.broadcast('worktrees:externalCreate', { repoRoot, worktree: created, initialPrompt })
+    deps.broadcast('worktrees:externalCreate', {
+      repoRoot,
+      worktree: created,
+      initialPrompt,
+      agentKind,
+      model
+    })
     return sendJson(res, 200, created)
   }
 
diff --git a/src/main/index.ts b/src/main/index.ts
index 02892e68..de332df5 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -318,11 +318,12 @@ const jsonClaudeManager = new JsonClaudeManager(store, {
       isMain: scope.isMain
     }
   },
-  getLaunchSettings: (worktreePath) =>
+  getLaunchSettings: (worktreePath, modelOverride) =>
     buildClaudeLaunchSettings({
       cwd: worktreePath,
       worktrees: store.getSnapshot().state.worktrees.list,
-      config
+      config,
+      modelOverride
     })
 })
 const perfMonitor = new PerfMonitor()
@@ -768,6 +769,24 @@ const panesFSM = new PanesFSM(store, {
   }
 })
 
+/** Look up a json-claude tab's persisted `model` override by sessionId
+ *  (which is also the tab id for json-claude tabs). Returned to the
+ *  json-claude manager so resume/kickoff/wake all respect a per-tab pin
+ *  that was set when the worktree was created. */
+function findJsonClaudeTabModel(sessionId: string): string | undefined {
+  const panes = store.getSnapshot().state.terminals.panes
+  for (const tree of Object.values(panes)) {
+    for (const leaf of getLeaves(tree)) {
+      for (const tab of leaf.tabs) {
+        if (tab.id === sessionId && tab.type === 'json-claude') {
+          return tab.model && tab.model.trim() ? tab.model.trim() : undefined
+        }
+      }
+    }
+  }
+  return undefined
+}
+
 /** Single source of truth for "spin up the json-claude subprocess for
  *  this sessionId". Used by the jsonClaude:start IPC handler, the
  *  panesFSM's startJsonClaudeWithPrompt + startJsonClaude options
@@ -789,16 +808,16 @@ function startJsonClaudeSession(sessionId: string, worktreePath: string): void {
   const permMode =
     store.getSnapshot().state.jsonClaude.sessions[sessionId]?.permissionMode ||
     'default'
-  jsonClaudeManager.create(sessionId, worktreePath, permMode)
+  jsonClaudeManager.create(sessionId, worktreePath, permMode, findJsonClaudeTabModel(sessionId))
 }
 
 const worktreesFSM = new WorktreesFSM(store, {
   getRepoRoots: () => config.repoRoots || [],
   getWorktreeSetupCmd: () => config.worktreeSetupCommand || '',
   getWorktreeBaseMode: () => config.worktreeBase || DEFAULT_WORKTREE_BASE,
-  onWorktreeCreated: ({ createdPath, initialPrompt, teleportSessionId }) => {
+  onWorktreeCreated: ({ createdPath, initialPrompt, teleportSessionId, agentKind, model }) => {
     void prPoller.refreshAll()
-    panesFSM.ensureInitialized(createdPath, { initialPrompt, teleportSessionId })
+    panesFSM.ensureInitialized(createdPath, { initialPrompt, teleportSessionId, agentKind, model })
     if (teleportSessionId) {
       setTimeout(() => void worktreesFSM.refreshList(), 10_000)
     }
@@ -974,13 +993,25 @@ function registerIpcHandlers(): void {
       branchName: string
       initialPrompt?: string
       teleportSessionId?: string
+      agentKind?: 'claude' | 'codex'
+      model?: string
     }) => {
       return worktreesFSM.runPending(params)
     }
   )
   transport.onRequest(
     'worktrees:runPendingPR',
-    async (_ctx, params: { id: string; repoRoot: string; prNumber: number }) => {
+    async (
+      _ctx,
+      params: {
+        id: string
+        repoRoot: string
+        prNumber: number
+        initialPrompt?: string
+        agentKind?: 'claude' | 'codex'
+        model?: string
+      }
+    ) => {
       return worktreesFSM.runPendingPR(params)
     }
   )
@@ -2079,7 +2110,10 @@ function registerIpcHandlers(): void {
     (_ctx, agentKind: string, opts: {
       terminalId: string; cwd: string; sessionId?: string;
       initialPrompt?: string; teleportSessionId?: string;
-      sessionName?: string
+      sessionName?: string;
+      /** Per-tab model override (TerminalTab.model). When set, wins over
+       *  the global claudeModel/codexModel setting. */
+      modelOverride?: string
     }): string => {
       const kind = toAgentKind(agentKind)
       const agent = getAgent(kind)
@@ -2091,6 +2125,7 @@ function registerIpcHandlers(): void {
         resolveCallerScope(opts.terminalId)
       )
 
+      const override = opts.modelOverride && opts.modelOverride.trim() ? opts.modelOverride.trim() : undefined
       let systemPrompt: string | undefined
       let tuiFullscreen: boolean | undefined
       let model: string | null
@@ -2098,13 +2133,14 @@ function registerIpcHandlers(): void {
         const launch = buildClaudeLaunchSettings({
           cwd: opts.cwd,
           worktrees: store.getSnapshot().state.worktrees.list,
-          config
+          config,
+          modelOverride: override
         })
         systemPrompt = launch.systemPrompt
         tuiFullscreen = launch.tuiFullscreen
         model = launch.model ?? null
       } else {
-        model = config.codexModel || null
+        model = override || config.codexModel || null
       }
 
       return agent.buildSpawnArgs({ ...opts, command, mcpConfigPath, model, systemPrompt, tuiFullscreen })
@@ -3144,9 +3180,13 @@ async function runBoot(): Promise<void> {
           repoRoot: string
           worktree: { path: string }
           initialPrompt?: string
+          agentKind?: 'claude' | 'codex'
+          model?: string
         }
         panesFSM.ensureInitialized(p.worktree.path, {
-          initialPrompt: p.initialPrompt
+          initialPrompt: p.initialPrompt,
+          agentKind: p.agentKind,
+          model: p.model
         })
         void worktreesFSM.refreshList().then(() => {
           broadcastToAllWindows(channel, payload)
diff --git a/src/main/json-claude-manager.ts b/src/main/json-claude-manager.ts
index 01af3db5..730b8d92 100644
--- a/src/main/json-claude-manager.ts
+++ b/src/main/json-claude-manager.ts
@@ -120,7 +120,7 @@ export interface JsonClaudeManagerOptions {
    *  --name) at spawn time from the live config + worktree list. Same
    *  source of truth as the xterm spawn path; see buildClaudeLaunchSettings
    *  in claude-launch.ts. */
-  getLaunchSettings: (worktreePath: string) => ClaudeLaunchSettings
+  getLaunchSettings: (worktreePath: string, modelOverride?: string) => ClaudeLaunchSettings
 }
 
 /** Path to the bundled stdio MCP server we point Claude's
@@ -364,7 +364,10 @@ export class JsonClaudeManager {
   create(
     sessionId: string,
     worktreePath: string,
-    permissionMode: JsonClaudePermissionMode = 'default'
+    permissionMode: JsonClaudePermissionMode = 'default',
+    /** Per-tab model override. When set, wins over the global claudeModel
+     *  setting via buildClaudeLaunchSettings. */
+    modelOverride?: string
   ): void {
     if (this.instances.has(sessionId)) {
       log('json-claude', `create no-op — already running sessionId=${sessionId}`)
@@ -432,7 +435,7 @@ export class JsonClaudeManager {
       ? ['--resume', sessionId]
       : ['--session-id', sessionId]
 
-    const launchSettings = this.opts.getLaunchSettings(worktreePath)
+    const launchSettings = this.opts.getLaunchSettings(worktreePath, modelOverride)
     const args = [
       '-p',
       '--input-format',
diff --git a/src/main/panes-fsm.ts b/src/main/panes-fsm.ts
index 9b2f58dd..b1741fb0 100644
--- a/src/main/panes-fsm.ts
+++ b/src/main/panes-fsm.ts
@@ -190,7 +190,15 @@ export class PanesFSM {
 
   ensureInitialized(
     wtPath: string,
-    opts?: { initialPrompt?: string; teleportSessionId?: string }
+    opts?: {
+      initialPrompt?: string
+      teleportSessionId?: string
+      /** Override the default agent kind for this worktree's first tab. */
+      agentKind?: AgentKind
+      /** Override the default model (claudeModel/codexModel setting) for
+       *  this worktree's first tab. Empty/undefined = use settings. */
+      model?: string
+    }
   ): PaneNode {
     const existing = this.getTree(wtPath)
     if (existing && hasAnyTabs(existing)) return existing
@@ -202,8 +210,9 @@ export class PanesFSM {
       return sleeping
     }
 
-    const agentKind = this.opts.getDefaultAgentKind?.() ?? 'claude'
+    const agentKind = opts?.agentKind ?? this.opts.getDefaultAgentKind?.() ?? 'claude'
     const agentInfo = getAgentInfo(agentKind)
+    const model = opts?.model && opts.model.trim() ? opts.model.trim() : undefined
     const shellTabId = `shell-${wtPath}-${Date.now()}`
     // Branch to a json-claude default tab when the user has opted in
     // and the kind is Claude. teleport sessions stay on xterm (json-
@@ -216,7 +225,7 @@ export class PanesFSM {
       this.opts.getDefaultClaudeTabType?.() === 'json' &&
       !opts?.teleportSessionId
     let agentTab: TerminalTab
-    let jsonClaudeKickoff: { sessionId: string; initialPrompt?: string } | null = null
+    let jsonClaudeKickoff: { sessionId: string; initialPrompt?: string; model?: string } | null = null
     if (wantsJson) {
       const sessionId = crypto.randomUUID()
       agentTab = {
@@ -224,9 +233,10 @@ export class PanesFSM {
         type: 'json-claude',
         label: 'Claude (JSON)',
         sessionId,
-        mode: 'awake'
+        mode: 'awake',
+        model
       }
-      jsonClaudeKickoff = { sessionId, initialPrompt: opts?.initialPrompt }
+      jsonClaudeKickoff = { sessionId, initialPrompt: opts?.initialPrompt, model }
     } else {
       const agentTabId = `agent-${wtPath.replace(/[^a-zA-Z0-9]/g, '-')}-${Date.now()}`
       agentTab = {
@@ -236,7 +246,8 @@ export class PanesFSM {
         label: agentInfo.displayName,
         sessionId: agentInfo.assignsSessionId ? crypto.randomUUID() : undefined,
         initialPrompt: opts?.teleportSessionId ? undefined : opts?.initialPrompt,
-        teleportSessionId: opts?.teleportSessionId
+        teleportSessionId: opts?.teleportSessionId,
+        model
       }
     }
     const tabs: TerminalTab[] = [agentTab, { id: shellTabId, type: 'shell', label: 'Shell' }]
diff --git a/src/main/worktrees-fsm.ts b/src/main/worktrees-fsm.ts
index 68df9d8f..aa1c8dfa 100644
--- a/src/main/worktrees-fsm.ts
+++ b/src/main/worktrees-fsm.ts
@@ -62,6 +62,10 @@ interface WorktreesFSMOptions {
     createdPath: string
     initialPrompt?: string
     teleportSessionId?: string
+    /** Override the default agent kind for the new worktree's first tab. */
+    agentKind?: 'claude' | 'codex'
+    /** Override the default model for the new worktree's first tab. */
+    model?: string
   }) => void
 }
 
@@ -111,8 +115,10 @@ export class WorktreesFSM {
     branchName: string
     initialPrompt?: string
     teleportSessionId?: string
+    agentKind?: 'claude' | 'codex'
+    model?: string
   }): Promise<PendingOutcome> {
-    const { id, repoRoot, branchName, initialPrompt, teleportSessionId } = params
+    const { id, repoRoot, branchName, initialPrompt, teleportSessionId, agentKind, model } = params
     const pending: PendingWorktree = {
       id,
       repoRoot,
@@ -134,7 +140,9 @@ export class WorktreesFSM {
         repoRoot,
         created,
         initialPrompt,
-        teleportSessionId
+        teleportSessionId,
+        agentKind,
+        model
       })
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err)
@@ -155,8 +163,10 @@ export class WorktreesFSM {
     repoRoot: string
     prNumber: number
     initialPrompt?: string
+    agentKind?: 'claude' | 'codex'
+    model?: string
   }): Promise<PendingOutcome> {
-    const { id, repoRoot, prNumber, initialPrompt } = params
+    const { id, repoRoot, prNumber, initialPrompt, agentKind, model } = params
     // Show *something* while we go ask GitHub for the head ref name.
     let branchName = `pr-${prNumber}`
     const pending: PendingWorktree = {
@@ -191,7 +201,9 @@ export class WorktreesFSM {
         id,
         repoRoot,
         created,
-        initialPrompt
+        initialPrompt,
+        agentKind,
+        model
       })
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err)
@@ -211,8 +223,10 @@ export class WorktreesFSM {
     created: WorktreeInfo
     initialPrompt?: string
     teleportSessionId?: string
+    agentKind?: 'claude' | 'codex'
+    model?: string
   }): Promise<PendingOutcome> {
-    const { id, repoRoot, created, initialPrompt, teleportSessionId } = args
+    const { id, repoRoot, created, initialPrompt, teleportSessionId, agentKind, model } = args
 
     const setupCmd = this.resolveSetupCmd(repoRoot)
     let setupFailed = false
@@ -246,7 +260,9 @@ export class WorktreesFSM {
     this.opts.onWorktreeCreated({
       createdPath: created.path,
       initialPrompt,
-      teleportSessionId
+      teleportSessionId,
+      agentKind,
+      model
     })
     await this.refreshList()
 
diff --git a/src/renderer/build-backend.ts b/src/renderer/build-backend.ts
index 6e84c898..59c3cf48 100644
--- a/src/renderer/build-backend.ts
+++ b/src/renderer/build-backend.ts
@@ -101,12 +101,16 @@ export function buildBackend(
       branchName: string
       initialPrompt?: string
       teleportSessionId?: string
+      agentKind?: 'claude' | 'codex'
+      model?: string
     }) => req('worktrees:runPending', params),
     runPendingPRWorktree: (params: {
       id: string
       repoRoot: string
       prNumber: number
       initialPrompt?: string
+      agentKind?: 'claude' | 'codex'
+      model?: string
     }) => req('worktrees:runPendingPR', params),
     retryPendingWorktree: (id: string) => req('worktrees:retryPending', id),
     dismissPendingWorktree: (id: string) => req('worktrees:dismissPending', id),
@@ -316,6 +320,7 @@ export function buildBackend(
         initialPrompt?: string
         teleportSessionId?: string
         sessionName?: string
+        modelOverride?: string
       }
     ) => req('agent:buildSpawnArgs', agentKind, opts),
 
diff --git a/src/renderer/components/MobileTerminal.tsx b/src/renderer/components/MobileTerminal.tsx
index 09e22bfe..1b743a83 100644
--- a/src/renderer/components/MobileTerminal.tsx
+++ b/src/renderer/components/MobileTerminal.tsx
@@ -306,6 +306,7 @@ export function MobileTerminal({ worktreePath, tab }: MobileTerminalProps): JSX.
           visible={true}
           sessionName={tab.label}
           sessionId={tab.sessionId}
+          modelOverride={tab.type === 'agent' ? tab.model : undefined}
         />
         {/* Hidden textarea — pointer-events:none so touch scrolling on the
             wrapper above isn't eaten; the wrapper's onClick focuses the
diff --git a/src/renderer/components/NewWorktreeScreen.tsx b/src/renderer/components/NewWorktreeScreen.tsx
index 2beb10a4..d120dc2f 100644
--- a/src/renderer/components/NewWorktreeScreen.tsx
+++ b/src/renderer/components/NewWorktreeScreen.tsx
@@ -8,8 +8,21 @@ import { useSettings } from '../store'
 import type { PRSummary } from '../types'
 
 interface NewWorktreeScreenProps {
-  onSubmit: (repoRoot: string, branchName: string, initialPrompt: string, teleportSessionId?: string) => Promise<void>
-  onPRSubmit: (repoRoot: string, prNumber: number, initialPrompt: string) => Promise<void>
+  onSubmit: (
+    repoRoot: string,
+    branchName: string,
+    initialPrompt: string,
+    teleportSessionId?: string,
+    agentKind?: 'claude' | 'codex',
+    model?: string
+  ) => Promise<void>
+  onPRSubmit: (
+    repoRoot: string,
+    prNumber: number,
+    initialPrompt: string,
+    agentKind?: 'claude' | 'codex',
+    model?: string
+  ) => Promise<void>
   onCancel: () => void
   repoRoots: string[]
   /** Repo to pre-select in the picker. Usually the repo of the currently active worktree. */
@@ -80,6 +93,14 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
   const settings = useSettings()
   const [reviewPrompt, setReviewPrompt] = useState(settings.prReviewPrompt)
   const [teleportInput, setTeleportInput] = useState('')
+  // Per-creation overrides for agent + model. Default agent comes from
+  // settings; model defaults to empty (= use settings.claudeModel/codexModel
+  // at spawn time). Teleport mode pins to Claude — codex has no equivalent
+  // "resume by id" flow today.
+  const [agentKindOverride, setAgentKindOverride] = useState<'claude' | 'codex'>(
+    settings.defaultAgent === 'codex' ? 'codex' : 'claude'
+  )
+  const [modelOverride, setModelOverride] = useState('')
   const [submitting, setSubmitting] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const branchRef = useRef<HTMLInputElement>(null)
@@ -146,13 +167,19 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
       setPrClickPending(prNumber)
       setError(null)
       try {
-        await onPRSubmit(selectedRepo, prNumber, reviewPrompt.trim())
+        await onPRSubmit(
+          selectedRepo,
+          prNumber,
+          reviewPrompt.trim(),
+          agentKindOverride,
+          modelOverride.trim() || undefined
+        )
       } catch (err) {
         setError(err instanceof Error ? err.message : 'Failed to open PR')
         setPrClickPending(null)
       }
     },
-    [onPRSubmit, prClickPending, selectedRepo, reviewPrompt]
+    [onPRSubmit, prClickPending, selectedRepo, reviewPrompt, agentKindOverride, modelOverride]
   )
 
   const handleBranchChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
@@ -164,12 +191,23 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
     setSubmitting(true)
     setError(null)
     try {
-      await onSubmit(selectedRepo, effectiveBranch, prompt.trim(), parsedTeleport || undefined)
+      // Teleport mode always Claude — codex has no resume-by-session-id
+      // analog today.
+      const effectiveAgent: 'claude' | 'codex' =
+        mode === 'teleport' ? 'claude' : agentKindOverride
+      await onSubmit(
+        selectedRepo,
+        effectiveBranch,
+        prompt.trim(),
+        parsedTeleport || undefined,
+        effectiveAgent,
+        modelOverride.trim() || undefined
+      )
     } catch (err) {
       setError(err instanceof Error ? err.message : 'Failed to create worktree')
       setSubmitting(false)
     }
-  }, [effectiveBranch, prompt, canSubmit, onSubmit, parsedTeleport, selectedRepo])
+  }, [effectiveBranch, prompt, canSubmit, onSubmit, parsedTeleport, selectedRepo, mode, agentKindOverride, modelOverride])
 
   const cycleRepo = useCallback((direction: 1 | -1) => {
     if (repoRoots.length <= 1) return
@@ -424,6 +462,16 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
                     className="w-full bg-app border-2 border-border-strong rounded-lg px-4 py-3 text-sm text-fg-bright placeholder-faint outline-none focus:border-accent transition-colors resize-none"
                   />
                 </label>
+                <AgentModelRow
+                  mode={mode}
+                  agentKind={agentKindOverride}
+                  setAgentKind={setAgentKindOverride}
+                  model={modelOverride}
+                  setModel={setModelOverride}
+                  defaultClaudeModel={settings.claudeModel}
+                  defaultCodexModel={settings.codexModel}
+                  disabled={prClickPending !== null}
+                />
                 <PRPickerList
                   prs={prsByRepo[selectedRepo]}
                   loading={prsLoadingRepo === selectedRepo}
@@ -435,6 +483,19 @@ export function NewWorktreeScreen({ onSubmit, onPRSubmit, onCancel, repoRoots, d
               </>
             )}
 
+            {mode !== 'pr' && (
+              <AgentModelRow
+                mode={mode}
+                agentKind={agentKindOverride}
+                setAgentKind={setAgentKindOverride}
+                model={modelOverride}
+                setModel={setModelOverride}
+                defaultClaudeModel={settings.claudeModel}
+                defaultCodexModel={settings.codexModel}
+                disabled={submitting}
+              />
+            )}
+
             {error && (
               <div className="mt-4 text-sm text-danger bg-danger/10 border border-danger/30 rounded-lg px-3 py-2">
                 {error}
@@ -602,3 +663,69 @@ function PRPickerList({ prs, loading, error, disabled, pendingNumber, onPick }:
     </div>
   )
 }
+
+interface AgentModelRowProps {
+  mode: 'fresh' | 'teleport' | 'pr'
+  agentKind: 'claude' | 'codex'
+  setAgentKind: (k: 'claude' | 'codex') => void
+  model: string
+  setModel: (m: string) => void
+  defaultClaudeModel: string | null
+  defaultCodexModel: string | null
+  disabled: boolean
+}
+
+function AgentModelRow({
+  mode,
+  agentKind,
+  setAgentKind,
+  model,
+  setModel,
+  defaultClaudeModel,
+  defaultCodexModel,
+  disabled
+}: AgentModelRowProps): JSX.Element {
+  // Teleport mode pins to Claude — codex has no equivalent
+  // "resume by session id" today. Lock the selector so users don't
+  // think they can flip it.
+  const locked = mode === 'teleport'
+  const effectiveAgent = locked ? 'claude' : agentKind
+  const placeholder =
+    effectiveAgent === 'codex'
+      ? defaultCodexModel || 'default'
+      : defaultClaudeModel || 'default'
+  return (
+    <div className="flex items-center gap-3 mt-5">
+      <div className="flex items-center gap-2">
+        <span className="text-[11px] font-semibold uppercase tracking-wider text-dim">
+          Agent
+        </span>
+        <select
+          value={effectiveAgent}
+          onChange={(e) => setAgentKind(e.target.value === 'codex' ? 'codex' : 'claude')}
+          disabled={disabled || locked}
+          title={locked ? 'Teleport sessions require Claude' : undefined}
+          className="bg-app border border-border-strong rounded px-2 py-1 text-xs text-fg-bright outline-none focus:border-accent disabled:opacity-50"
+        >
+          <option value="claude">Claude</option>
+          <option value="codex">Codex</option>
+        </select>
+      </div>
+      <div className="flex items-center gap-2 flex-1 min-w-0">
+        <span className="text-[11px] font-semibold uppercase tracking-wider text-dim shrink-0">
+          Model
+        </span>
+        <input
+          type="text"
+          value={model}
+          onChange={(e) => setModel(e.target.value)}
+          placeholder={placeholder}
+          disabled={disabled}
+          spellCheck={false}
+          autoComplete="off"
+          className="flex-1 min-w-0 bg-app border border-border-strong rounded px-2 py-1 text-xs font-mono text-fg-bright placeholder-faint outline-none focus:border-accent disabled:opacity-50"
+        />
+      </div>
+    </div>
+  )
+}
diff --git a/src/renderer/components/WorkspaceView.tsx b/src/renderer/components/WorkspaceView.tsx
index af0eba83..a84fb1d0 100644
--- a/src/renderer/components/WorkspaceView.tsx
+++ b/src/renderer/components/WorkspaceView.tsx
@@ -582,6 +582,7 @@ export function WorkspaceView({
                     sessionId={tab.sessionId}
                     initialPrompt={tab.initialPrompt}
                     teleportSessionId={tab.teleportSessionId}
+                    modelOverride={tab.type === 'agent' ? tab.model : undefined}
                     shellCommand={tab.type === 'shell' ? tab.command : undefined}
                     shellCwd={tab.type === 'shell' ? tab.cwd : undefined}
                     onRestartAgent={
diff --git a/src/renderer/components/XTerminal.tsx b/src/renderer/components/XTerminal.tsx
index 24eb27be..f2d6a245 100644
--- a/src/renderer/components/XTerminal.tsx
+++ b/src/renderer/components/XTerminal.tsx
@@ -181,6 +181,9 @@ interface XTerminalProps {
   sessionId?: string
   initialPrompt?: string
   teleportSessionId?: string
+  /** Agent tabs only: per-tab model override. When set, wins over the global
+   *  claudeModel/codexModel setting at spawn time. */
+  modelOverride?: string
   /** Shell tabs only: when set, spawn `<user-shell> -ilc <command>` instead
    * of an interactive login shell. Used for agent-spawned shells. */
   shellCommand?: string
@@ -190,7 +193,7 @@ interface XTerminalProps {
   onRestartAgent?: () => void
 }
 
-export function XTerminal({ terminalId, cwd, type, agentKind, visible, sessionName, sessionId, initialPrompt, teleportSessionId, shellCommand, shellCwd, onRestartAgent }: XTerminalProps): JSX.Element {
+export function XTerminal({ terminalId, cwd, type, agentKind, visible, sessionName, sessionId, initialPrompt, teleportSessionId, modelOverride, shellCommand, shellCwd, onRestartAgent }: XTerminalProps): JSX.Element {
   // Lazy font-cache init — fires once on first XTerminal mount. See
   // initFontCache() comment for why this is lazy rather than at module
   // top.
@@ -337,7 +340,8 @@ export function XTerminal({ terminalId, cwd, type, agentKind, visible, sessionNa
         sessionId,
         initialPrompt,
         teleportSessionId,
-        sessionName
+        sessionName,
+        modelOverride
       })
     }
 
diff --git a/src/renderer/hooks/useWorktreeHandlers.ts b/src/renderer/hooks/useWorktreeHandlers.ts
index e8219771..b57621c7 100644
--- a/src/renderer/hooks/useWorktreeHandlers.ts
+++ b/src/renderer/hooks/useWorktreeHandlers.ts
@@ -161,20 +161,24 @@ export function useWorktreeHandlers(args: UseWorktreeHandlersArgs) {
       repoRoot: string,
       branchName: string,
       initialPrompt: string,
-      teleportSessionId?: string
+      teleportSessionId?: string,
+      agentKind?: 'claude' | 'codex',
+      model?: string
     ) => {
       const id = `pending:${crypto.randomUUID()}`
       setActiveWorktreeId(id)
       setShowNewWorktree(false)
 
       // Main handles everything: addWorktree → setup script → ensureInitialized
-      // (with the prompt embedded in the new Claude tab) → outcome.
+      // (with the prompt embedded in the new agent tab) → outcome.
       const result = await backend.runPendingWorktree({
         id,
         repoRoot,
         branchName,
         initialPrompt: initialPrompt || undefined,
-        teleportSessionId
+        teleportSessionId,
+        agentKind,
+        model
       })
 
       if (result.outcome === 'success') {
@@ -188,7 +192,13 @@ export function useWorktreeHandlers(args: UseWorktreeHandlersArgs) {
   )
 
   const handleSubmitNewPRWorktree = useCallback(
-    async (repoRoot: string, prNumber: number, initialPrompt: string) => {
+    async (
+      repoRoot: string,
+      prNumber: number,
+      initialPrompt: string,
+      agentKind?: 'claude' | 'codex',
+      model?: string
+    ) => {
       const id = `pending:${crypto.randomUUID()}`
       setActiveWorktreeId(id)
       setShowNewWorktree(false)
@@ -197,7 +207,9 @@ export function useWorktreeHandlers(args: UseWorktreeHandlersArgs) {
         id,
         repoRoot,
         prNumber,
-        initialPrompt: initialPrompt || undefined
+        initialPrompt: initialPrompt || undefined,
+        agentKind,
+        model
       })
 
       if (result.outcome === 'success') {
diff --git a/src/renderer/types.ts b/src/renderer/types.ts
index 3c867e43..25875873 100644
--- a/src/renderer/types.ts
+++ b/src/renderer/types.ts
@@ -169,6 +169,8 @@ export interface ElectronAPI {
     branchName: string
     initialPrompt?: string
     teleportSessionId?: string
+    agentKind?: 'claude' | 'codex'
+    model?: string
   }): Promise<
     | { id: string; outcome: 'success'; createdPath: string }
     | { id: string; outcome: 'setup-failed'; createdPath: string }
@@ -179,6 +181,8 @@ export interface ElectronAPI {
     repoRoot: string
     prNumber: number
     initialPrompt?: string
+    agentKind?: 'claude' | 'codex'
+    model?: string
   }): Promise<
     | { id: string; outcome: 'success'; createdPath: string }
     | { id: string; outcome: 'setup-failed'; createdPath: string }
@@ -388,7 +392,7 @@ export interface ElectronAPI {
   buildAgentSpawnArgs(agentKind: string, opts: {
     terminalId: string; cwd: string; sessionId?: string;
     initialPrompt?: string; teleportSessionId?: string;
-    sessionName?: string
+    sessionName?: string; modelOverride?: string
   }): Promise<string>
 
   hasGithubToken(): Promise<boolean>
diff --git a/src/shared/state/terminals.ts b/src/shared/state/terminals.ts
index 05ac6b4d..b4e9ab0f 100644
--- a/src/shared/state/terminals.ts
+++ b/src/shared/state/terminals.ts
@@ -24,6 +24,11 @@ export interface TerminalTab {
   mode?: 'awake' | 'asleep'
   /** For agent tabs: which CLI agent this tab runs. */
   agentKind?: AgentKind
+  /** For agent + json-claude tabs: override the model resolved from
+   *  settings (claudeModel/codexModel). Set when a worktree was spawned
+   *  with a one-shot pick (New Worktree screen "Model" field or the MCP
+   *  create_worktree `model` param). Empty/undefined = use settings. */
+  model?: string
   /** For diff/file tabs: the file path */
   filePath?: string
   /** For diff tabs: whether the diff is for staged changes */

From 707c2ab776d5a55352a0a837c0cb41c9c8b3db5a Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Mon, 25 May 2026 08:54:23 -0600
Subject: [PATCH 5/7] hide agent + model row behind an "Advanced" collapser
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Auto-expands when either field has a non-default value (so a typed
model or a Codex pick isn't hidden), and shows a compact
"(Claude · sonnet)" hint next to the collapsed header.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/renderer/components/NewWorktreeScreen.tsx | 91 ++++++++++++-------
 1 file changed, 59 insertions(+), 32 deletions(-)

diff --git a/src/renderer/components/NewWorktreeScreen.tsx b/src/renderer/components/NewWorktreeScreen.tsx
index d120dc2f..379594d0 100644
--- a/src/renderer/components/NewWorktreeScreen.tsx
+++ b/src/renderer/components/NewWorktreeScreen.tsx
@@ -1,5 +1,5 @@
 import { useState, useCallback, useEffect, useRef } from 'react'
-import { Sparkles, Loader2, X, Map, ListChecks, BookOpen, Radio, GitPullRequest } from 'lucide-react'
+import { Sparkles, Loader2, X, Map, ListChecks, BookOpen, Radio, GitPullRequest, ChevronRight, ChevronDown } from 'lucide-react'
 import iconUrl from '../../../resources/icon.png'
 import { sanitizeBranchInput, isValidBranchName } from '../branch-name'
 import { RepoIcon } from './RepoIcon'
@@ -694,38 +694,65 @@ function AgentModelRow({
     effectiveAgent === 'codex'
       ? defaultCodexModel || 'default'
       : defaultClaudeModel || 'default'
+
+  // Auto-open when the user has typed a model override OR picked a non-
+  // claude agent — so a state that's already non-default isn't hidden
+  // behind a collapsed header. Plain `useState` here makes the open flag
+  // sticky once the user expands; collapsing again is always a click.
+  const [openOverride, setOpenOverride] = useState(false)
+  const hasNonDefault = (!locked && agentKind !== 'claude') || model.trim().length > 0
+  const open = openOverride || hasNonDefault
+
   return (
-    <div className="flex items-center gap-3 mt-5">
-      <div className="flex items-center gap-2">
-        <span className="text-[11px] font-semibold uppercase tracking-wider text-dim">
-          Agent
-        </span>
-        <select
-          value={effectiveAgent}
-          onChange={(e) => setAgentKind(e.target.value === 'codex' ? 'codex' : 'claude')}
-          disabled={disabled || locked}
-          title={locked ? 'Teleport sessions require Claude' : undefined}
-          className="bg-app border border-border-strong rounded px-2 py-1 text-xs text-fg-bright outline-none focus:border-accent disabled:opacity-50"
-        >
-          <option value="claude">Claude</option>
-          <option value="codex">Codex</option>
-        </select>
-      </div>
-      <div className="flex items-center gap-2 flex-1 min-w-0">
-        <span className="text-[11px] font-semibold uppercase tracking-wider text-dim shrink-0">
-          Model
-        </span>
-        <input
-          type="text"
-          value={model}
-          onChange={(e) => setModel(e.target.value)}
-          placeholder={placeholder}
-          disabled={disabled}
-          spellCheck={false}
-          autoComplete="off"
-          className="flex-1 min-w-0 bg-app border border-border-strong rounded px-2 py-1 text-xs font-mono text-fg-bright placeholder-faint outline-none focus:border-accent disabled:opacity-50"
-        />
-      </div>
+    <div className="mt-5">
+      <button
+        type="button"
+        onClick={() => setOpenOverride((v) => !v)}
+        className="flex items-center gap-1.5 text-[11px] font-semibold uppercase tracking-wider text-dim hover:text-fg transition-colors cursor-pointer"
+      >
+        {open ? <ChevronDown size={12} /> : <ChevronRight size={12} />}
+        Advanced
+        {!open && hasNonDefault && (
+          <span className="ml-1 normal-case font-normal tracking-normal text-faint">
+            ({effectiveAgent === 'codex' ? 'Codex' : 'Claude'}
+            {model.trim() ? ` · ${model.trim()}` : ''})
+          </span>
+        )}
+      </button>
+      {open && (
+        <div className="flex items-center gap-3 mt-3">
+          <div className="flex items-center gap-2">
+            <span className="text-[11px] font-semibold uppercase tracking-wider text-dim">
+              Agent
+            </span>
+            <select
+              value={effectiveAgent}
+              onChange={(e) => setAgentKind(e.target.value === 'codex' ? 'codex' : 'claude')}
+              disabled={disabled || locked}
+              title={locked ? 'Teleport sessions require Claude' : undefined}
+              className="bg-app border border-border-strong rounded px-2 py-1 text-xs text-fg-bright outline-none focus:border-accent disabled:opacity-50"
+            >
+              <option value="claude">Claude</option>
+              <option value="codex">Codex</option>
+            </select>
+          </div>
+          <div className="flex items-center gap-2 flex-1 min-w-0">
+            <span className="text-[11px] font-semibold uppercase tracking-wider text-dim shrink-0">
+              Model
+            </span>
+            <input
+              type="text"
+              value={model}
+              onChange={(e) => setModel(e.target.value)}
+              placeholder={placeholder}
+              disabled={disabled}
+              spellCheck={false}
+              autoComplete="off"
+              className="flex-1 min-w-0 bg-app border border-border-strong rounded px-2 py-1 text-xs font-mono text-fg-bright placeholder-faint outline-none focus:border-accent disabled:opacity-50"
+            />
+          </div>
+        </div>
+      )}
     </div>
   )
 }

From 5e70ec474a047737bebddf3375303be91110a071 Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Mon, 25 May 2026 08:58:15 -0600
Subject: [PATCH 6/7] use the Settings model dropdown on the New Worktree
 screen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mirrors the Current/Legacy optgroup pattern from Settings → Agent →
Claude/Codex so the per-creation override picks from the same list of
known models the rest of the app uses (no more free-typing a string
that might not even exist). Switching agent kind also clears the model
so a stale Claude id can't be sent as Codex's --model flag.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/renderer/components/NewWorktreeScreen.tsx | 50 +++++++++++++------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/src/renderer/components/NewWorktreeScreen.tsx b/src/renderer/components/NewWorktreeScreen.tsx
index 379594d0..998ee347 100644
--- a/src/renderer/components/NewWorktreeScreen.tsx
+++ b/src/renderer/components/NewWorktreeScreen.tsx
@@ -5,6 +5,7 @@ import { sanitizeBranchInput, isValidBranchName } from '../branch-name'
 import { RepoIcon } from './RepoIcon'
 import { useBackend } from '../backend'
 import { useSettings } from '../store'
+import { CLAUDE_MODELS, CODEX_MODELS } from '../../shared/agent-registry'
 import type { PRSummary } from '../types'
 
 interface NewWorktreeScreenProps {
@@ -690,10 +691,14 @@ function AgentModelRow({
   // think they can flip it.
   const locked = mode === 'teleport'
   const effectiveAgent = locked ? 'claude' : agentKind
-  const placeholder =
-    effectiveAgent === 'codex'
-      ? defaultCodexModel || 'default'
-      : defaultClaudeModel || 'default'
+  const modelOptions = effectiveAgent === 'codex' ? CODEX_MODELS : CLAUDE_MODELS
+  const fallbackModel =
+    effectiveAgent === 'codex' ? defaultCodexModel : defaultClaudeModel
+  const fallbackDisplay =
+    modelOptions.find((m) => m.id === fallbackModel)?.displayName || fallbackModel
+  const defaultLabel = fallbackDisplay
+    ? `(Default — settings: ${fallbackDisplay})`
+    : '(Default — let CLI choose)'
 
   // Auto-open when the user has typed a model override OR picked a non-
   // claude agent — so a state that's already non-default isn't hidden
@@ -703,6 +708,15 @@ function AgentModelRow({
   const hasNonDefault = (!locked && agentKind !== 'claude') || model.trim().length > 0
   const open = openOverride || hasNonDefault
 
+  const handleAgentChange = (next: 'claude' | 'codex'): void => {
+    // Reset the model when switching agents — otherwise a stale Claude
+    // model id would be sent as Codex's --model flag (or vice versa).
+    if (next !== agentKind) setModel('')
+    setAgentKind(next)
+  }
+
+  const modelDisplay = modelOptions.find((m) => m.id === model)?.displayName || model
+
   return (
     <div className="mt-5">
       <button
@@ -715,7 +729,7 @@ function AgentModelRow({
         {!open && hasNonDefault && (
           <span className="ml-1 normal-case font-normal tracking-normal text-faint">
             ({effectiveAgent === 'codex' ? 'Codex' : 'Claude'}
-            {model.trim() ? ` · ${model.trim()}` : ''})
+            {model.trim() ? ` · ${modelDisplay}` : ''})
           </span>
         )}
       </button>
@@ -727,10 +741,10 @@ function AgentModelRow({
             </span>
             <select
               value={effectiveAgent}
-              onChange={(e) => setAgentKind(e.target.value === 'codex' ? 'codex' : 'claude')}
+              onChange={(e) => handleAgentChange(e.target.value === 'codex' ? 'codex' : 'claude')}
               disabled={disabled || locked}
               title={locked ? 'Teleport sessions require Claude' : undefined}
-              className="bg-app border border-border-strong rounded px-2 py-1 text-xs text-fg-bright outline-none focus:border-accent disabled:opacity-50"
+              className="bg-app border border-border-strong rounded px-2 py-1 text-xs text-fg-bright outline-none focus:border-accent disabled:opacity-50 cursor-pointer"
             >
               <option value="claude">Claude</option>
               <option value="codex">Codex</option>
@@ -740,16 +754,24 @@ function AgentModelRow({
             <span className="text-[11px] font-semibold uppercase tracking-wider text-dim shrink-0">
               Model
             </span>
-            <input
-              type="text"
+            <select
               value={model}
               onChange={(e) => setModel(e.target.value)}
-              placeholder={placeholder}
               disabled={disabled}
-              spellCheck={false}
-              autoComplete="off"
-              className="flex-1 min-w-0 bg-app border border-border-strong rounded px-2 py-1 text-xs font-mono text-fg-bright placeholder-faint outline-none focus:border-accent disabled:opacity-50"
-            />
+              className="flex-1 min-w-0 bg-app border border-border-strong rounded px-2 py-1 text-xs text-fg-bright outline-none focus:border-accent disabled:opacity-50 cursor-pointer"
+            >
+              <option value="">{defaultLabel}</option>
+              <optgroup label="Current">
+                {modelOptions.filter((m) => m.tier === 'current').map((m) => (
+                  <option key={m.id} value={m.id}>{m.displayName}</option>
+                ))}
+              </optgroup>
+              <optgroup label="Legacy">
+                {modelOptions.filter((m) => m.tier === 'legacy').map((m) => (
+                  <option key={m.id} value={m.id}>{m.displayName}</option>
+                ))}
+              </optgroup>
+            </select>
           </div>
         </div>
       )}

From 6c8dc80a3d77e36da00043f34f4640a2a3728bbf Mon Sep 17 00:00:00 2001
From: Mike Lyons <mdl0394@gmail.com>
Date: Mon, 25 May 2026 09:19:24 -0600
Subject: [PATCH 7/7] fix: persist tab.model across reloads + review cleanup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Self-review caught that TerminalTab.model was being dropped on every
persistence cycle:

- PersistedTab schema didn't list it, so the type system silently
  accepted serializers that omitted it.
- treeToPersistedNode (src/main/index.ts) built the persisted object
  from an explicit field list — model wasn't there.
- hydratePersistedTree (src/main/panes-fsm.ts) rebuilt TerminalTab
  from the same explicit list, so even a model that made it to disk
  would be dropped on read.

Adding model to all three closes the loop. The pattern matches every
other persistent tab field (agentKind, sessionId, cwd, command — none
of which have round-trip tests either, so this follows existing
conventions: the type system + explicit field lists are the contract).

Also:

- Trimmed duplicate "override the default…" comments that just
  restated the field types. Kept the canonical one on the
  TerminalTab.model slice field.
- Threaded agentKind + model through the host's runPendingPRWorktree
  broadcast payload so its shape stays in sync with the new-branch
  path's deps.broadcast call. Today the FSM already applies them via
  onWorktreeCreated, but a future consolidation refactor would
  silently lose data otherwise.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/main/claude-launch.ts             |  2 --
 src/main/index.ts                     | 13 +++++++++----
 src/main/json-claude-manager.ts       |  2 --
 src/main/panes-fsm.ts                 |  6 ++----
 src/main/persistence-migrations.ts    |  3 +++
 src/main/worktrees-fsm.ts             |  2 --
 src/renderer/components/XTerminal.tsx |  2 --
 7 files changed, 14 insertions(+), 16 deletions(-)

diff --git a/src/main/claude-launch.ts b/src/main/claude-launch.ts
index f85a869d..a26302d4 100644
--- a/src/main/claude-launch.ts
+++ b/src/main/claude-launch.ts
@@ -28,8 +28,6 @@ export function buildClaudeLaunchSettings(input: {
   cwd: string
   worktrees: Worktree[]
   config: ClaudeLaunchConfig
-  /** Per-tab model override. When set (and non-empty after trim), wins
-   *  over `config.claudeModel`. */
   modelOverride?: string
 }): ClaudeLaunchSettings {
   const { cwd, worktrees, config, modelOverride } = input
diff --git a/src/main/index.ts b/src/main/index.ts
index de332df5..a14d7867 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -693,7 +693,8 @@ function treeToPersistedNode(node: PaneNode): PersistedPaneNode | null {
           sessionId: stripped.sessionId,
           url: liveUrl || stripped.url,
           command: stripped.command,
-          cwd: stripped.cwd
+          cwd: stripped.cwd,
+          model: stripped.model
         }
       })
     if (tabs.length === 0) return null
@@ -2111,8 +2112,6 @@ function registerIpcHandlers(): void {
       terminalId: string; cwd: string; sessionId?: string;
       initialPrompt?: string; teleportSessionId?: string;
       sessionName?: string;
-      /** Per-tab model override (TerminalTab.model). When set, wins over
-       *  the global claudeModel/codexModel setting. */
       modelOverride?: string
     }): string => {
       const kind = toAgentKind(agentKind)
@@ -3161,10 +3160,16 @@ async function runBoot(): Promise<void> {
       if (!found) {
         return { ok: false, error: `created worktree at ${outcome.createdPath} but couldn't resolve its branch` }
       }
+      // agentKind + model are already applied via the FSM's onWorktreeCreated
+      // path; we still ship them in the broadcast payload so its shape stays
+      // in sync with the new-branch path through deps.broadcast — keeps
+      // future refactors that consolidate the two from silently losing data.
       broadcastToAllWindows('worktrees:externalCreate', {
         repoRoot: params.repoRoot,
         worktree: found,
-        initialPrompt: params.initialPrompt
+        initialPrompt: params.initialPrompt,
+        agentKind: params.agentKind,
+        model: params.model
       })
       return { ok: true, path: found.path, branch: found.branch }
     },
diff --git a/src/main/json-claude-manager.ts b/src/main/json-claude-manager.ts
index 730b8d92..cb6f3d62 100644
--- a/src/main/json-claude-manager.ts
+++ b/src/main/json-claude-manager.ts
@@ -365,8 +365,6 @@ export class JsonClaudeManager {
     sessionId: string,
     worktreePath: string,
     permissionMode: JsonClaudePermissionMode = 'default',
-    /** Per-tab model override. When set, wins over the global claudeModel
-     *  setting via buildClaudeLaunchSettings. */
     modelOverride?: string
   ): void {
     if (this.instances.has(sessionId)) {
diff --git a/src/main/panes-fsm.ts b/src/main/panes-fsm.ts
index b1741fb0..e2625e4d 100644
--- a/src/main/panes-fsm.ts
+++ b/src/main/panes-fsm.ts
@@ -165,7 +165,8 @@ export class PanesFSM {
         sessionId: t.sessionId,
         url: t.url,
         command: t.command,
-        cwd: t.cwd
+        cwd: t.cwd,
+        model: t.model
       }
       // Persisted json-claude tabs hydrate as 'asleep' so app launch
       // doesn't spawn one subprocess per tab. The renderer wakes them
@@ -193,10 +194,7 @@ export class PanesFSM {
     opts?: {
       initialPrompt?: string
       teleportSessionId?: string
-      /** Override the default agent kind for this worktree's first tab. */
       agentKind?: AgentKind
-      /** Override the default model (claudeModel/codexModel setting) for
-       *  this worktree's first tab. Empty/undefined = use settings. */
       model?: string
     }
   ): PaneNode {
diff --git a/src/main/persistence-migrations.ts b/src/main/persistence-migrations.ts
index 74581b6c..2ef867b0 100644
--- a/src/main/persistence-migrations.ts
+++ b/src/main/persistence-migrations.ts
@@ -28,6 +28,9 @@ export interface PersistedTab {
   command?: string
   /** For shell tabs: cwd (absolute or relative to worktree root). */
   cwd?: string
+  /** For agent + json-claude tabs: per-tab model pin. Wins over the
+   *  global claudeModel/codexModel setting at spawn time. */
+  model?: string
 }
 
 export interface PersistedPane {
diff --git a/src/main/worktrees-fsm.ts b/src/main/worktrees-fsm.ts
index aa1c8dfa..9cb53a28 100644
--- a/src/main/worktrees-fsm.ts
+++ b/src/main/worktrees-fsm.ts
@@ -62,9 +62,7 @@ interface WorktreesFSMOptions {
     createdPath: string
     initialPrompt?: string
     teleportSessionId?: string
-    /** Override the default agent kind for the new worktree's first tab. */
     agentKind?: 'claude' | 'codex'
-    /** Override the default model for the new worktree's first tab. */
     model?: string
   }) => void
 }
diff --git a/src/renderer/components/XTerminal.tsx b/src/renderer/components/XTerminal.tsx
index f2d6a245..c6212c28 100644
--- a/src/renderer/components/XTerminal.tsx
+++ b/src/renderer/components/XTerminal.tsx
@@ -181,8 +181,6 @@ interface XTerminalProps {
   sessionId?: string
   initialPrompt?: string
   teleportSessionId?: string
-  /** Agent tabs only: per-tab model override. When set, wins over the global
-   *  claudeModel/codexModel setting at spawn time. */
   modelOverride?: string
   /** Shell tabs only: when set, spawn `<user-shell> -ilc <command>` instead
    * of an interactive login shell. Used for agent-spawned shells. */