v1.20.5 — Sub-agent delivery quality + ADR-083 Phase 2 cleanup

Release date: 2026-05-14

Fixes the four compounding failure modes of delegate_to_sub_agent_tool observed since the ADR-083 Phase 1bis rollout: GraphRecursionError with 47-char outputs, 80+ tools exposed burning the recursion budget, 120 s timeout starving slow-reasoning loops, and response_node compressing 26 KB of expert analysis to 2 KB while overlaying the assistant's conversational voice.

Sub-agent quality fixes

• SUBAGENT_DEFAULT_MAX_ITERATIONS default 5 → 10 (ceiling 15 → 30). LangGraph counts each node visit as one superstep; 5 starved any plan with 4+ parallel searches in pass 1.
• New SUBAGENT_RESEARCH_TOOLS_WHITELIST env (default brave_search_tool,fetch_web_page_tool, snake_case CSV with field_validator rejecting dashes / semicolons / uppercase / leading digits at config-load time) switches resolve_tools_for_subagent to allowlist mode. Keeps the sub-agent focused on factual verification instead of exploring the full ~80-tool catalogue.
• Dedicated SUBAGENT_TOOL_TIMEOUT_SECONDS floor (default 180, range 30-600) + SUBAGENT_TOOL_MAX_TIMEOUT_SECONDS ceiling (default 300, range 60-900), wired in parallel_executor via a tool_name == "delegate_to_sub_agent_tool" branch. Generic MAX_TOOL_TIMEOUT_SECONDS = 120 unchanged for other tools. Per-tool-family timeout policy extracted to a pure _compute_step_timeout helper (27 unit tests).
• subagent_react_prompt.txt rewritten from ~17 to ~65 lines: explicit value contract, task calibration lexicon (analyse / synthèse / résumé / comparaison → adapted output forms), epistemic rigor protocol, execution discipline (1-3 tool rounds preferred), explicit negative voice anchor (no sarcasm / no "tour de contrôle" rhetoric), NO markdown tables directive, 6-question pre-emit self-check, 7 documented anti-patterns.
• Deterministic <SubAgentAnalysis> tag wrap in formatters/agent_results.py + new <SubAgentDeliveryOverride> block in response_system_prompt_base.txt that keys off the tag (not an LLM heuristic) and mandates verbatim restitution — no compression, no rewriting in the assistant's conversational voice, one-sentence intro allowed.
• Validator drift fixes: recency enum on unified_web_search_tool extended to include 'year' (the runtime _normalize_recency already accepted it); expertise max_length on delegate_to_sub_agent_tool bumped from 500 → 2000.

ADR-083 Phase 2 cleanup

Legacy persistent sub-agent plumbing removed: bespoke SubAgentExecutor pipeline, /sub-agents REST API, user-defined templates, sub_agents DB table, per-user sub_agents_enabled toggle, daily Redis budget, stale-recovery scheduler. The ephemeral ReactSubAgentRunner path is now the only consumer.

Two Alembic migrations: drop_sub_agents_table_and_parent_run_id, drop_users_sub_agents_enabled.

Documentation drift correction

docs/knowledge/13_sub_agents.md rewritten to reflect the ADR-083 Phase 2 architecture (removed references to the deleted Settings UI). FAQ q3 in 6 locales reworded: no longer points at the deleted user toggle, explains admin-level activation and per-delegation HITL control.

Tests

7 736 unit tests pass. New coverage:

• tests/unit/test_subagent_settings.py — 21 cases
• tests/unit/domains/sub_agents/test_subagent_prompt.py — 9 cases
• tests/unit/domains/agents/formatters/test_agent_results_subagent_wrap.py — 12 cases
• tests/unit/domains/agents/orchestration/test_parallel_executor_compute_step_timeout.py — 27 cases

Documentation

• docs/technical/SUB_AGENTS.md: env vars table, "Why dedicated timeout + whitelist" section, "Response Node — Verbatim Delivery Override" section
• README.md top banner promoted to v1.20.5 (v1.20.4 demoted to <details>)
• docs/GETTING_STARTED.md compatibility line bumped to v1.20.5
• In-app FAQ (6 languages): new faq.changelog.versions.v1_20_5 entry — 3 user/admin items focused on observable quality improvement
• Version bumped across apps/api/pyproject.toml, apps/web/package.json, package.json, apps/web/src/lib/version.ts (LAST_UPDATED = 2026-05-14T17:30:00)

See CHANGELOG.md for the full breakdown.

🤖 Generated with Claude Code