agents.max_threads "When unset, no limit is enforced" is back in config_toml.rs and config.schema.json (regression of #13964)

What version of Codex CLI is running?

codex-cli 0.144.6 (macOS arm64). Source inspected at tag rust-v0.144.6 → commit 5d1fbf26c43abc65a203928b2e31561cb039e06d.

What issue are you seeing?

#13964 reported that agents.max_threads' doc text — "When unset, no limit is enforced" — contradicts the runtime, which substitutes DEFAULT_AGENT_MAX_THREADS = Some(6). It was closed COMPLETED on 2026-03-08 with "This is now fixed in the docs."

The text is present again at 0.144.6. It looks like the fix landed in the file #13964 named, but the struct subsequently moved to a new crate and carried the stale comment with it — and the generated schema, which #13964 also explicitly named, was never regenerated.

State at the pinned commit:

| Location | Status |
|---|---|
| codex-rs/core/src/config/mod.rs | ✅ text absent — the original fix is intact here |
| codex-rs/config/src/config_toml.rs:684-685 | ❌ text present — this is the live AgentsToml definition |
| codex-rs/core/config.schema.json | ❌ text present — generated from the above |

codex-rs/config/src/config_toml.rs:683-691:

pub struct AgentsToml {
    /// Maximum number of agent threads that can be open concurrently.
    /// When unset, no limit is enforced.
    #[schemars(range(min = 1))]
    pub max_threads: Option<usize>,
    /// Maximum nesting depth allowed for spawned agent threads.
    /// Root sessions start at depth 0.
    #[schemars(range(min = 1))]
    pub max_depth: Option<i32>,

Contradicted by codex-rs/core/src/config/mod.rs:

pub(crate) const DEFAULT_AGENT_MAX_THREADS: Option<usize> = Some(6);

applied in effective_agent_max_threads as self.agent_max_threads.or(DEFAULT_AGENT_MAX_THREADS).

Expected behavior

Unset agents.max_threads documented as defaulting to 6, in both the doc comment and the regenerated config.schema.json.

Actual behavior

Both state that no limit is enforced when unset.

Suggested fix

Correct the comment in config_toml.rs and regenerate codex-rs/core/config.schema.json. A schema-drift check in CI would prevent the regeneration step from being missed again, since the doc comment is the schema's source of truth and the two are now out of sync.

Adjacent, low-cost while you're in this struct

max_depth's comment states "Root sessions start at depth 0" but not that it defaults to 1 — the one number a reader most needs, since the default permits exactly one layer of subagents. Adding it would close the same class of gap. (Worth noting agents.max_depth does not appear in docs/config.md at this tag at all.)

Additional context

Found while smoke-testing subagent depth limits on 0.144.6. Not user-impacting on its own, but it compounds: max_threads and max_depth are easy to conflate, and both are currently under-documented relative to their effect on subagent behaviour.