Codex Desktop: agent handoff tool lacks parity with the Handoff UI

What variant of Codex are you using?

Codex Desktop for Windows, version 26.721.4979.0.

What feature would you like to see?

Expose the full Codex Desktop Handoff operation to the agent.

The Desktop UI can hand off the current task between Local and Worktree and lets the user choose which branch remains checked out in the Local workspace.

The agent-facing handoff_thread tool cannot perform the equivalent operation:

• It requires the ID of another task and rejects attempts to hand off the calling task.
• Its input contains only threadId, optional destinationHostId, and optional followUpPrompt.
• It does not expose the UI's Local checkout branch selection.
• For a local-to-worktree handoff, the current implementation selects the repository default branch for the Local checkout.

This causes a concrete problem in repositories where the GitHub default branch is not the day-to-day development branch.

For example:

• repository default branch: main
• development branch: dev
• task branch created from: origin/dev

In the UI, the user can hand the task branch to a worktree and set Local workspace will switch to dev.

The agent tool has no way to request that. It selects main, so an automated workflow must either stop and ask the user to use the UI or create a separate coordinator task, hand off another task, and repair the Local checkout afterward.

Expected behavior

The agent should be able to perform the same safe handoff available in the UI.

That could mean:

1. Allowing the calling task to schedule its own handoff as the final action of a turn, with continuation in the destination task.
2. Adding a localCheckoutBranch parameter equivalent to the UI selector.
3. Applying the same cleanliness, branch ownership, and worktree validations used by the UI.
4. Preserving the existing progress reporting and followUpPrompt continuation behavior.

User approval requirements do not need to change. The goal is capability parity after the user has explicitly requested the handoff.

Why this matters

Workflows and skills cannot fully automate a normal Codex Desktop operation that the user can already perform safely through the UI. They must either interrupt the user for mechanical clicks or introduce an unnecessary multi-task orchestration workaround.

Related issues

• #16531 requests synchronization when an agent creates a worktree manually. This issue concerns the newer native handoff_thread tool lacking parity with the existing Handoff UI.
• #29223 concerns whether thread-management tools are available at all. In this case the tool is present but does not expose the required operation.
• #32775 also encounters the self-handoff restriction, but in a projectless, cross-host automation workflow.