Expose worktree-aware thread environment APIs in Codex SDK/app-server

What variant of Codex are you using?

SDK

What feature would you like to see?

Summary

The Codex SDK currently lets callers start, resume, and fork threads with a cwd, but external tools need a first-class way to express:

• the parent Codex project / repository identity
• the execution checkout / working directory
• whether that checkout should be local, a new Codex-managed worktree, or an existing Git linked worktree

Right now, cwd alone cannot represent those separately.

Current behavior

In the SDK/API surface I can find, thread operations accept cwd / working-directory style parameters, but not a first-class worktree environment model.

Examples:

• Python SDK methods expose cwd on thread_start, thread_resume, thread_fork, and turn/run methods.
• TypeScript SDK docs expose workingDirectory.
• I do not see SDK/app-server parameters equivalent to the Codex App's project-targeted local vs. worktree environment model.
• I do not see an API to attach or adopt an existing Git linked worktree after a thread has started.

Observed locally with:

• openai-codex: 0.1.0b3
• openai-codex-cli-bin: 0.137.0a4

Why cwd alone is not enough

External clients often need these workflows:

1. Create a thread under a known project, but have Codex create a fresh isolated worktree.
2. Create a thread under a known project, but run it inside an existing linked worktree.
3. Fork or delegate to another thread and request a worktree-backed execution environment.
4. Attach an existing thread to a linked worktree after the thread has already started.

With only cwd, callers have to choose between incorrect tradeoffs:

• cwd = parent repo: project grouping may be correct, but the thread appears to be on the parent checkout/branch even if implementation happens elsewhere.
• cwd = linked worktree: execution is correct, but project grouping/history can fragment because the worktree is treated like a separate project.
• Agent creates or switches to a worktree after startup: there is no supported way to update or adopt that environment.

Desired API shape

The SDK/app-server should expose project identity and execution checkout as separate concepts.

Illustrative API shape:

codex.thread_start(
    project_root="/path/to/repo",
    environment={
        "type": "worktree",
        "mode": "create",
        "branch": "codex/my-task",
        "starting_state": {"type": "branch", "branch_name": "main"},
    },
)

For existing linked worktrees:

codex.thread_start(
    project_root="/path/to/repo",
    environment={
        "type": "existing_worktree",
        "cwd": "/path/to/repo-worktree",
        "branch": "codex/my-task",
    },
)

For already-started threads:

codex.thread_adopt_worktree(
    thread_id=thread_id,
    project_root="/path/to/repo",
    worktree_path="/path/to/repo-worktree",
)

Names are illustrative; the important part is the model:

• project identity is separate from execution cwd
• Codex-managed worktrees and existing Git linked worktrees are both representable
• adoption/refresh is possible after thread creation

Expected behavior

Threads created or adopted this way should:

• appear under the parent Codex project
• execute commands and file edits in the selected worktree
• show the actual worktree path/branch in the Codex App UI where applicable
• preserve sandbox/workspace behavior around the actual execution checkout
• work whether the linked worktree was created by Codex or by standard git worktree add

Related App/UI issues

This SDK/API request is related to, but distinct from, existing App/UI worktree issues:

• #26749 asks for reusable existing worktrees as project-level workspaces.
• #16531 covers agent-created worktrees not syncing with the active App thread/UI.
• #27693 covers persistent worktree binding in CLI/TUI behavior.
• #26861 and #28204 cover App-native create_thread worktree orchestration/pending-worktree issues.

Those issues show the product need. This issue is specifically about exposing the missing primitives to SDK/app-server clients.

Request

Please expose first-class worktree-aware thread creation, fork, resume, and adoption APIs in the Codex SDK/app-server, so external tools can create threads that preserve parent project identity while executing in either Codex-managed or existing linked worktrees.