@spec await(pid(), String.t(), keyword()) ::
  {:ok, terminal_turn_status()} | {:error, term()}

Polls a known child thread id until its latest turn reaches a terminal status.

This uses repeated thread/read(include_turns: true) calls and returns the latest terminal turn status.

@spec child_thread?(
  thread_map()
  | Codex.Protocol.SessionSource.t()
  | map()
  | String.t()
  | atom()
  | nil
) ::
  boolean()

Returns true when the thread/source carries an explicit parent-child spawn link.

@spec children(pid(), String.t(), keyword()) ::
  {:ok, [thread_map()]} | {:error, term()}

Lists spawned child threads for a known parent thread id.

@spec list(
  pid(),
  keyword()
) :: {:ok, [thread_map()]} | {:error, term()}

Lists subagent threads using thread/list.

This defaults source_kinds to [:sub_agent]. When you need pagination or other raw thread/list response metadata, use Codex.AppServer.thread_list/2 directly.

@spec parent_thread_id(
  thread_map()
  | Codex.Protocol.SessionSource.t()
  | map()
  | String.t()
  | atom()
  | nil
) :: String.t() | nil

Returns the parent thread id for a spawned child thread source, if present.

@spec read(pid(), String.t(), keyword()) :: {:ok, thread_map()} | {:error, term()}

Reads a known subagent thread using thread/read.

@spec source(
  thread_map()
  | Codex.Protocol.SessionSource.t()
  | map()
  | String.t()
  | atom()
  | nil
) ::
  Codex.Protocol.SessionSource.t()

Parses the typed source metadata for a thread map or raw source payload.