Codex App create_thread returns pendingWorktreeId without an addressable threadId

What version of the Codex App are you using (From “About Codex” dialog)?

26.602.40724 (3593)

What subscription do you have?

Unknown from the agent/tool context. This was observed inside Codex App while using thread-management tools.

What platform is your computer?

Darwin 25.5.0 arm64 arm

What issue are you seeing?

When an agent creates a new Codex-managed worktree thread through the app thread tool, create_thread may return only a pendingWorktreeId, for example:

{
  "pendingWorktreeId": "local:<uuid>"
}

At that point the orchestrating thread has no reliable way to address, inspect, amend, cancel, or monitor the pending child.

The available follow-up tools require a threadId, but the create result does not expose one yet. There also does not appear to be a tool to map pendingWorktreeId -> threadId, send a message to a pending worktree, read pending setup status, or cancel the pending setup.

This creates an orchestration gap:

• The parent can create a managed worktree request.
• Before the child materializes as a normal thread, the parent cannot update its instructions.
• If the child never becomes discoverable through list_threads, the parent has no reliable way to recover.
• If the initial prompt omitted an important instruction, the parent cannot amend it until the thread is discoverable.

This is particularly painful for multi-thread workflows where a parent/orchestrator thread is creating worker threads for repo work and needs to coordinate follow-up instructions, stop conditions, or cancellation.

Related but broader feature request: #14923. This issue is narrower: the pending worktree object returned by create_thread is not addressable from the thread-management tool surface.

What steps can reproduce the bug?

1. From a Codex App thread with thread-management tools available, create a new project thread using a Codex-managed worktree environment:

{
  "target": {
    "type": "project",
    "projectId": "/path/to/saved/project",
    "environment": {
      "type": "worktree",
      "startingState": {
        "type": "branch",
        "branchName": "some-existing-branch"
      }
    }
  },
  "prompt": "Start work in the managed worktree and report back."
}

1. Observe that the tool may return only:

{
  "pendingWorktreeId": "local:<uuid>"
}

1. Try to send an additional instruction before the new worktree thread appears.

Actual:

• send_message_to_thread cannot be used because there is no threadId.
• read_thread cannot be used because there is no threadId.
• list_threads may not reveal the pending child yet, and there is no guaranteed mapping from pendingWorktreeId to the eventual thread.
• There is no apparent read_pending_worktree, cancel_pending_worktree, or send_message_to_pending_worktree tool.

1. If the parent realizes the initial prompt needs correction, it cannot reliably amend or cancel the pending child.

What is the expected behavior?

One of these would make the workflow reliable:

1. create_thread returns both pendingWorktreeId and a reserved/future threadId that can receive queued messages or cancellation.
2. A pending-worktree API exists:

• read_pending_worktree(pendingWorktreeId)
• cancel_pending_worktree(pendingWorktreeId)
• send_message_to_pending_worktree(pendingWorktreeId, prompt)

1. A mapping API exists:

• resolve_pending_worktree(pendingWorktreeId) -> { status, threadId? }

1. The app emits a parent-visible completion event when the pending worktree materializes, including the new threadId.
2. list_threads can search by pendingWorktreeId and reliably return the eventual thread once available.

The key requirement is that the object returned by create_thread remains addressable through the tool surface until it either becomes a real thread or fails/cancels.

Additional information

This is not just a UI polish issue. It affects orchestration reliability:

• Parent/orchestrator threads need deterministic child lifecycle control.
• A pending child may need amended instructions before first run.
• A pending child may need cancellation if the parent discovers the branch/worktree setup was wrong.
• Without a threadId or pending-worktree control surface, the parent is forced to wait and hope the child appears in thread search.

Workaround:

• Put every possible instruction into the initial create_thread prompt.
• Wait for the child to materialize and try to discover it through list_threads.

That workaround is brittle because the parent cannot correct or cancel the pending request during the setup gap.