docs: fix config/subagent/tool-lifecycle truth drift (v0.9.9 docs scout)

[Hmbown]

Summary

Docs-only truth-up of four scout findings: config.example.toml spawn-depth and sub-agent concurrency comments, the docs/SUBAGENTS.md scout output-contract carve-out, and the docs/TOOL_LIFECYCLE.md checklist/todo replay contradiction.

Closes #5447

Verification

• Grepped/read DEFAULT_SPAWN_DEPTH / MAX_SPAWN_DEPTH_CEILING in crates/config/src/lib.rs and the clamp in crates/tui/src/tools/subagent/mod.rs.
• Grepped/read DEFAULT_MAX_SUBAGENTS / MAX_SUBAGENTS in crates/tui/src/config/subagent_limits.rs; confirmed docs/SUBAGENTS.md already matches.
• Grepped/read SUBAGENT_OUTPUT_FORMAT / SUBAGENT_SCOUT_OUTPUT_FORMAT in crates/tui/src/prompts/text.rs, FleetRole::system_prompt in crates/tui/src/tools/subagent/mod.rs, and the #5189 F5 scout test.
• Grepped/read ToolRegistryBuilder::with_todo_tool, TodoWriteTool::alias / model_visible, and rlm_is_the_only_registered_session_surface ("must no longer be callable" is the RLM retirement test, not checklist/todo).
• git add / git commit / git push -u origin codex/v099-docs-truth-batch.

Not verified: cargo (docs-only)
Not verified: python3 scripts/check-readme-translations.py (README.md untouched)

Checklist

• Updated docs or comments as needed
• Added or updated tests where relevant
• Verified TUI behavior manually if UI changes
• Harvested/co-authored credit uses a GitHub numeric noreply address

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @Hmbown's task in 1m 17s —— View job

---

Review: docs-only truth-up (config/subagent/tool-lifecycle)

Todos

• Gather context (read diff, changed files)
• Verify claims against source (spawn depth, subagent limits, output-contract carve-out, checklist/todo lifecycle)
• Review docs diff for correctness/accuracy
• Post final review

Summary

This is a docs-only PR (no .rs changes) fixing stale/inaccurate comments and prose in config.example.toml, docs/SUBAGENTS.md, and docs/TOOL_LIFECYCLE.md. I verified every factual claim in the diff against current source and all of them check out.

Verified accurate:

• config.example.toml:387 — max_subagents default/clamp comment now says "default 64, clamped to 1-128", matching DEFAULT_MAX_SUBAGENTS = 64 / MAX_SUBAGENTS = 128 in crates/tui/src/config/subagent_limits.rs:13,17.
• config.example.toml:398 — max_depth ceiling comment now says "clamped to the hard ceiling (8)", matching MAX_SPAWN_DEPTH_CEILING: u32 = 8 in crates/config/src/lib.rs:1741 (was previously wrong at 3, which is actually DEFAULT_SPAWN_DEPTH).
• docs/SUBAGENTS.md — the scout output-contract carve-out is real: FleetRole::system_prompt (crates/tui/src/tools/subagent/mod.rs:564-582) applies SUBAGENT_SCOUT_OUTPUT_FORMAT (SUMMARY+EVIDENCE only) exclusively to FleetRole::Scout and the full 5-heading SUBAGENT_OUTPUT_FORMAT to every other role. The pinning test is crates/tui/src/tools/subagent/tests.rs:2504-2521, and prompts.rs:3277 (prompt_documents_structured_subagent_briefs) is the correct current name/location for the heading assertion (the old prompts.rs:3222 citation was stale).
• docs/TOOL_LIFECYCLE.md — the registered hidden-compat alias set for todo_write is exactly work_update, TodoWrite, todo, checklist_write, checklist_update per ToolRegistryBuilder::with_todo_tool (crates/tui/src/tools/registry.rs:1330-1350); checklist_add, checklist_list, todo_add, todo_update, todo_list are never registered, consistent with the assertions in work_update_is_the_only_registered_progress_surface (registry/tests.rs:188-250). TodoWriteTool::model_visible (tools/todo.rs:258-260) confirms only the canonical name is model-visible.
• The doc now correctly attributes "must no longer be callable" to rlm_is_the_only_registered_session_surface (registry/tests.rs:253-278, testing rlm_* retirement), not to checklist/todo — this was a real mix-up in the old text.

Notes:

• Stale registry.rs:2290-2331 / registry.rs:1476-1490 line-number citations were removed rather than reworded, consistent with this doc's own stated policy of not re-pinning historical citations.
• Scope stayed docs-only as described; no code, test, or behavior changes.
• Good historical-hygiene practice: replacing brittle line-number citations with symbol/test names (ToolRegistryBuilder::with_todo_tool, TodoWriteTool::model_visible, etc.), which drift less over time than line numbers.

No correctness, safety, or reuse issues found. Nothing here touches provider/model routing.

[claude]

Claude finished @Hmbown's task in 1m 31s —— View job

---

Review: docs-only truth-up (config/subagent/tool-lifecycle)

Todos

• Gather context (diff, changed files)
• Verify claims against source (spawn depth, subagent limits, output-contract carve-out, checklist/todo lifecycle)
• Review docs diff for correctness/accuracy
• Post final review

Summary

Docs-only PR (no .rs changes). I independently re-verified every factual claim in the diff against current source on this branch; everything checks out.

Verified accurate:

• config.example.toml:387 — max_subagents comment now says "default 64, clamped to 1-128", matching DEFAULT_MAX_SUBAGENTS = 64 / MAX_SUBAGENTS = 128 in crates/tui/src/config/subagent_limits.rs:13,17.
• config.example.toml:398 — max_depth comment now says "clamped to the hard ceiling (8)", matching DEFAULT_SPAWN_DEPTH = 3 / MAX_SPAWN_DEPTH_CEILING = 8 in crates/config/src/lib.rs:1731,1741 (the old text wrongly said the ceiling was 3, which is actually the default).
• docs/SUBAGENTS.md scout carve-out — FleetRole::system_prompt (crates/tui/src/tools/subagent/mod.rs:564-582) applies SUBAGENT_SCOUT_OUTPUT_FORMAT only for FleetRole::Scout, SUBAGENT_OUTPUT_FORMAT for every other role. prompt_documents_structured_subagent_briefs exists at crates/tui/src/prompts.rs:3277. The scout pin test (## Output contract (scout) present, ### BLOCKERS absent) is real at crates/tui/src/tools/subagent/tests.rs:2505-2521.
• docs/TOOL_LIFECYCLE.md alias set — ToolRegistryBuilder::with_todo_tool (crates/tui/src/tools/registry.rs:1330-1350) registers exactly todo_write (canonical) plus aliases work_update, TodoWrite, todo, checklist_write, checklist_update. TodoWriteTool::model_visible (tools/todo.rs:258-260) is true only for the canonical name.
• The "must not be callable" quote for checklist_add/checklist_list/todo_add/todo_update/todo_list is a verbatim, exact match to the assertion message at crates/tui/src/core/engine/tests.rs:9059-9062 (assert!(!registry.contains(retired), "{retired} must not be callable")) — this is a real, non-registered set, not just hidden from the catalog.
• rlm_is_the_only_registered_session_surface (registry/tests.rs:253-278) is correctly attributed to rlm_* retirement, not checklist/todo — confirms the old doc's mix-up is fixed.
• shell_surface_exposes_lowercase_bash_and_hides_legacy_handler (registry/tests.rs:1348-1357) confirms exec_wait/exec_interact are genuinely unregistered (!registry.contains(...)), matching the doc's claim they were removed rather than kept hidden-compat.
• tts remains dispatchable via with_speech_tools (registry.rs:1055-1066).

Note (pre-existing, not introduced by this PR): the §4 deprecation table itself (further down in docs/TOOL_LIFECYCLE.md) still lists replay_supported = Yes for every row, including exec_wait/exec_interact and the never-registered todo_add/todo_update/todo_list/checklist_add/checklist_list — which now reads as inconsistent with the corrected callout text directly above it ("false for exec_wait/exec_interact and for the unregistered checklist/todo names"). This table is explicitly framed as the historical/rejected #2681 proposal rather than current truth, and the PR didn't touch the table rows, so this isn't a regression — just a pre-existing rough edge future doc work could tighten.

No correctness, provider/model-routing, reuse, or security issues — this PR touches no code paths. Scope stayed docs-only as described.