Make the sub-agent surface easier for less-capable models to drive:
- Unify role/type vocabulary (#2649): normalize_role_alias now accepts the
full set SubAgentType::from_str accepts (reviewer/implementer/verifier/...),
and SubAgentType::from_str learns `planner`, so the dual-validation pass no
longer rejects natural roles with a stale four-value hint. Error strings and
schema descriptions now enumerate the real accepted aliases.
- agent_eval/agent_close always active (#2605) so a first call executes instead
of hydrating its schema and forcing a double-invoke; both accept an
`agent_name` session alias (#2650).
- Self-diagnosing name conflicts (#2656): the duplicate-name error names the
conflicting agent_id and its status.
- Self-describing completion sentinels (#2658): subagent.done now carries
result_clipped / summary_complete / next_action so the parent knows whether
to trust the previous-line summary or call agent_eval.
- Actionable child-model-unavailable diagnostics (#2653): a provider 403/404
is annotated with the model id and recovery path instead of a bare error.
Tests: role vocabulary acceptance + error wording, agent_name resolution,
duplicate-name diagnostics, clipped-result sentinel, child-model annotation,
agent_eval/agent_close default-active. Full tui suite green (3948), clippy clean.
Targets codex/v0.8.53 (v0.8.53 stabilization).
The role taxonomy expansion in #404 added Implementer + Verifier as
distinct postures alongside General / Explore / Plan / Review /
Custom. The issue body explicitly lists \`docs/AGENTS.md or
docs/SUBAGENTS.md\` as a target file; this commit creates that file.
Coverage:
- Role taxonomy table — stance, write/shell access, typical use per
role.
- "When to pick which role" — narrative guidance the model can read
if the role choice isn't obvious.
- Alias map — every accepted spelling routed to a canonical role,
matching what \`SubAgentType::from_str\` accepts.
- Concurrency cap — the 10-by-default value, the
\`[subagents].max_concurrent\` knob, and the running-only
semantics (#509).
- Lifecycle — Pending → Running → terminal states, plus
\`Interrupted\` after a process restart.
- Session boundaries (#405) — \`session_boot_id\` mechanics,
default current-session filter, \`include_archived=true\` escape
hatch, pre-#405 record handling.
- Output contract — the SUMMARY/CHANGES/EVIDENCE/RISKS/BLOCKERS
format every sub-agent must produce.
- Memory + \`remember\` integration (#489) — sub-agents inherit the
parent's memory file when memory is enabled and can append durable
notes.
- Implementation notes — source path, persisted state file,
is_running semantics, RwLock pattern.
Cross-link added in \`docs/TOOL_SURFACE.md\` so the sub-agent section
points to this doc.
No Rust code changed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hunter B