# `Codex.Subagents`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.16.1/lib/codex/subagents.ex#L1)

Deterministic host-side helpers for working with subagent threads over app-server.

This module intentionally does not expose prompt-shaping operations such as
spawning or delegating work. It only wraps host-callable thread inspection and
polling behavior.

# `terminal_turn_status`

```elixir
@type terminal_turn_status() :: :completed | :failed | :interrupted
```

# `thread_map`

```elixir
@type thread_map() :: map()
```

# `await`

```elixir
@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.

# `child_thread?`

```elixir
@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.

# `children`

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

Lists spawned child threads for a known parent thread id.

# `list`

```elixir
@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.

# `parent_thread_id`

```elixir
@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.

# `read`

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

Reads a known subagent thread using `thread/read`.

# `source`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*