fix(subagent): clearer role vocab, lifecycle signals, and eval ergonomics (v0.8.53)

[Hmbown]

Part of the v0.8.53 stabilization cycle (PR group 3 — subagent usability & lifecycle). Targets the integration branch codex/v0.8.53.

Issues addressed

• subagents: role/schema mismatch makes agent_open hard to use correctly #2649 — role/type schema confusion: normalize_role_alias now accepts the full set that SubAgentType::from_str accepts (reviewer, implementer, verifier, …), and from_str learns planner. The dual-validation pass no longer rejects a natural role (e.g. role: "reviewer") with a stale worker, explorer, awaiter, default hint. All four role-error strings and the four model-facing schema descriptions now enumerate the real accepted vocabulary.
• agent_eval returns 'deferred and now loaded' requiring double invocation #2605 — agent_eval/agent_close are now in DEFAULT_ACTIVE_NATIVE_TOOLS, so a first call executes instead of hydrating its schema and forcing a deferred double-invoke.
• subagents: agent_eval rejects natural agent_name field #2650 — agent_eval/agent_close accept an agent_name alias for the session name (the field models naturally reach for).
• subagents: session name conflicts are hard for agents to diagnose #2656 — the duplicate session-name error now names the conflicting agent_id and its status, so a model can recover deterministically.
• subagents: completion events are hard for agents to coordinate from #2658 — the <codewhale:subagent.done> sentinel now carries result_clipped / summary_complete / next_action (use_summary vs call_agent_eval), kept lean (no embedded result). base.md integration-protocol prose updated to match.
• subagents: unavailable child model can look like a protected-content or authorization failure #2653 — a child-model-unavailable failure (provider 403/404, classified Authorization/State) is annotated with the model id and recovery path instead of surfacing a bare error.

Scope / deconfliction

• Owns the normalize_role_alias + role-error-string change for the cycle. The WS5 tool/deferred/error UX PR (tools: validation errors still leave agents doing schema trial-and-error #2659) will only add likely_field_corrections entries, so the two do not collide.
• DEFAULT_ACTIVE_NATIVE_TOOLS additions are alphabetical (agent_close/agent_eval before agent_open), keeping the prefix-cache partition sorted/byte-stable; non-overlapping with the WS5 git_log/git_show additions.
• Deferred (not in this PR): spawn-time child-model availability pre-check (needs registry plumbing), clipped-evaluation-output labeling (subagents: clipped evaluation output can be mistaken for complete evidence #2652).

Verification

• cargo test -p codewhale-tui --bins → 3948 passed, 0 failed.
• cargo clippy -p codewhale-tui --bins → clean.
• New tests: full role-vocabulary acceptance + error wording, agent_name session resolution, duplicate-name diagnostics, clipped-result sentinel, child-model annotation, and agent_eval/agent_close default-active.

🤖 Generated with Claude Code

[greptile-apps]

Hmbown has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.

[gemini-code-assist]

Code Review

This pull request enhances the sub-agent management system by keeping agent_eval and agent_close active to prevent double-invoking, expanding and aligning the accepted role aliases (e.g., adding planner, reviewer, verifier, and tool_agent aliases), and introducing self-describing completion fields (result_clipped, summary_complete, next_action) to the sub-agent sentinel. It also improves error handling by annotating child model access errors with actionable recovery hints and providing clearer duplicate session name errors. Relevant tests and documentation have been updated accordingly. There are no review comments to address, so no additional feedback is provided.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.