From 4cfca3c5ce3f9604ae959e0a7fbb30a0322a7e47 Mon Sep 17 00:00:00 2001 From: Friel Date: Sun, 23 Nov 2025 11:49:47 -0800 Subject: [PATCH] Clarify subagent flag docs --- codex-rs/core/root_agent_prompt.md | 7 ++++++- codex-rs/docs/protocol_v1.md | 3 +++ docs/config.md | 2 ++ 3 files changed, 11 insertions(+), 1 deletion(-) diff --git a/codex-rs/core/root_agent_prompt.md b/codex-rs/core/root_agent_prompt.md index 68cf9343c4..89997a125b 100644 --- a/codex-rs/core/root_agent_prompt.md +++ b/codex-rs/core/root_agent_prompt.md @@ -2,7 +2,12 @@ You are the **root agent** in a multi‑agent Codex session. Your job is to solve the user’s task end‑to‑end. Use subagents as semi‑autonomous workers when that makes the work simpler, safer, or more parallel, and otherwise act directly in the conversation as a normal assistant. -Subagent behavior and limits are configured via `config.toml` settings such as `max_active_subagents`, `root_agent_uses_user_messages`, `subagent_root_inbox_autosubmit`, and `subagent_inbox_inject_before_tools`. +Subagent behavior and limits are configured via `config.toml` knobs documented under the [feature flags section](../../docs/config.md#feature-flags). Enable the `subagent_tools` feature flag there before relying on the helpers, then tune the following settings: + +- `max_active_subagents` (`../../docs/config.md#max_active_subagents`) caps how many subagent sessions may run concurrently so you keep CPU/memory demand bounded. +- `root_agent_uses_user_messages` (`../../docs/config.md#root_agent_uses_user_messages`) controls whether the child sees your `subagent_send_message` text as a normal user turn or must read it from the tool output. +- `subagent_root_inbox_autosubmit` (`../../docs/config.md#subagent_root_inbox_autosubmit`) determines whether the root automatically drains its inbox and optionally starts follow-up turns when messages arrive. +- `subagent_inbox_inject_before_tools` (`../../docs/config.md#subagent_inbox_inject_before_tools`) chooses whether synthetic `subagent_await` calls are recorded before or after the real tool outputs for a turn. Use subagents as follows: diff --git a/codex-rs/docs/protocol_v1.md b/codex-rs/docs/protocol_v1.md index afa2f03453..5a67d62f39 100644 --- a/codex-rs/docs/protocol_v1.md +++ b/codex-rs/docs/protocol_v1.md @@ -50,6 +50,9 @@ When a `Turn` completes, the `response_id` from the `Model`'s final `response.co Each `Session` still runs at most one `Task` at a time. For parallel work, you can either run multiple Codex sessions or use subagents (via the `subagent_*` tools) to orchestrate multiple child sessions within a single daemon. +Subagent sessions run in parallel with the root thread, so you scale overlapping conversations without launching new daemons. +Enable the `subagent_tools` feature flag (see `../../docs/config.md#feature-flags`) and tune how many child sessions stay active with `max_active_subagents` (`../../docs/config.md#max_active_subagents`). + ## Interface - `Codex` diff --git a/docs/config.md b/docs/config.md index 5d08ed1547..af56b827fe 100644 --- a/docs/config.md +++ b/docs/config.md @@ -383,6 +383,8 @@ When `false`, cross-agent messages arrive only via `subagent_await` tool results ### subagent_root_inbox_autosubmit +> **Default:** `true`. + Controls whether the root agent automatically drains its inbox (and any child messages destined for agent `0`) at safe stopping points between model turns, and whether it may auto-start a follow-up turn based on those messages. When