johnnichev · johnnichev · Apr 13, 2026 · Apr 10, 2026 · Apr 10, 2026 · Apr 10, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -65,3 +65,7 @@ Apply to every public class/function in `__init__.py` exports:
 24. **`ConversationMemory.branch()` deep copy**: Use `dataclasses.replace()` on every Message. Restore `image_base64` explicitly (it's `init=False`).
 25. **SVG badge XML escaping**: Use `xml.sax.saxutils.escape()` for label/value interpolation.
 26. **`bandit` annotations**: Mark safe SQL with `# nosec B608`, safe subprocess with `# nosec B404`.
+27. **`aclosing()` for async generators**: `async for item in provider.astream(...)` MUST be wrapped in `async with aclosing(gen) as gen:` so the provider generator is deterministically closed on exception. Use `selectools._async_utils.aclosing` (Python 3.9 backport of `contextlib.aclosing`).
+28. **ContextVars propagation in `run_in_executor`**: Direct `loop.run_in_executor(None, fn)` drops `contextvars.Context` (OTel spans, Langfuse traces lost). Use `run_in_executor_copyctx(loop, executor, fn)` from `_async_utils.py`.
+29. **Malformed tool-call JSON recovery**: Provider `json.loads()` failures MUST surface via `ToolCall.parse_error`, not silent `return {}`. Use shared `_parse_tool_args()` helper. Tool executor checks `parse_error` before tool lookup.
+30. **Structured retry budget**: `RetryConfig.max_retries` controls structured-validation retries INDEPENDENTLY of `max_iterations`. Outer loop uses `max_iterations + ctx.structured_retries` so validation failures don't eat the tool budget.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -3,7 +3,7 @@
 Thank you for your interest in contributing to Selectools! We welcome contributions from the community.
 
 **Current Version:** v0.21.0
-**Test Status:** 5203 tests passing (95% coverage)
+**Test Status:** 5271 tests collected (95% coverage)
 **Python:** 3.9 – 3.13
 
 ## Getting Started
@@ -74,7 +74,7 @@ Similar to `npm run` scripts, here are the common commands for this project:
 ### Testing
 
 ```bash
-# Run all tests (5203 tests)
+# Run all tests (5271 tests)
 pytest tests/ -v
 
 # Run tests quietly (summary only)
@@ -264,7 +264,7 @@ selectools/
 │   ├── embeddings/             # Embedding providers
 │   ├── rag/                    # RAG: vector stores, chunking, loaders
 │   └── toolbox/                # 33 pre-built tools
-├── tests/                      # Test suite (5203 tests, 95% coverage)
+├── tests/                      # Test suite (5271 tests, 95% coverage)
 │   ├── agent/                  # Agent tests
 │   ├── rag/                    # RAG tests
 │   ├── tools/                  # Tool tests
@@ -371,7 +371,7 @@ We especially welcome contributions in these areas:
 - Add comparison guides (vs LangChain, LlamaIndex)
 
 ### 🧪 **Testing**
-- Increase test coverage (currently 5203 tests passing!)
+- Increase test coverage (currently 5271 tests collected!)
 - Add performance benchmarks
 - Improve E2E test stability with retry/rate-limit handling
 

diff --git a/README.md b/README.md
@@ -30,6 +30,40 @@ result = AgentGraph.chain(planner, writer, reviewer).run("Write a blog post")
 # selectools serve agent.yaml
 ```
 
+## What's New in v0.22
+
+### v0.22.0 — Competitor-Informed Bug Fixes
+
+22 bugs identified by mining 95+ closed bug reports from [Agno](https://github.com/agno-agi/agno) (39k stars) and 60+ from [PraisonAI](https://github.com/MervinPraison/PraisonAI) (6.9k stars), then cross-referencing the patterns against selectools v0.21.0 source code. Six were shipping blockers. All 22 are now fixed with TDD regression tests.
+
+```python
+# BUG-02: typing.Literal now supported in @tool()
+from typing import Literal
+from selectools.tools import tool
+
+@tool()
+def set_mode(mode: Literal["fast", "slow", "auto"]) -> str:
+    return f"mode={mode}"
+
+# BUG-14: session namespace isolation
+store.save("session_123", memory_a, namespace="agent_a")
+store.save("session_123", memory_b, namespace="agent_b")  # No collision
+
+# BUG-21: opt-in vector store search dedup
+results = store.search(query_embedding=emb, top_k=10, dedup=True)
+
+# BUG-03: sync APIs now work in Jupyter / FastAPI handlers
+agent.run("hello")  # Just works inside async contexts
+```
+
+- **6 HIGH severity** (shipping blockers): streaming dropped tool calls, `typing.Literal` crashed `@tool()`, `asyncio.run()` re-entry in 8 sync wrappers, HITL silently lost in parallel groups + subgraphs, `ConversationMemory` had no thread lock
+- **9 MEDIUM severity**: `<think>` tag stripping, RAG batch limits, MCP concurrent race, str→int/float/bool argument coercion, `Union[str, int]` support, multi-interrupt generators, GraphState fail-fast validation, session namespace isolation, summary growth cap
+- **7 LOW-MED severity**: cancelled-result extraction, `AgentTrace` lock, async observer exception logging, batch clone isolation, OTel/Langfuse observer locks, vector store search dedup, `Optional[T]` without default handling
+- **+57 new regression tests** in `tests/agent/test_regression.py`, each with empirical fault-injection verification (test fails without fix, passes after)
+- **Thread safety end-to-end correct** across `ConversationMemory`, `AgentTrace`, `OTelObserver`, `LangfuseObserver`, `MCPClient`, `FallbackProvider`, batch clone isolation
+
+See `CHANGELOG.md` for the full per-bug breakdown with cross-references to every original Agno/PraisonAI issue.
+
 ## What's New in v0.21
 
 ### v0.21.0 — Connector Expansion
@@ -73,7 +107,7 @@ The first AI agent framework to ship a visual graph builder in a single `pip ins
 
 **[Try the builder in your browser →](https://selectools.dev/builder/)** — no install required.
 
-[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/johnnichev/selectools/blob/main/notebooks/getting_started.ipynb) [![Examples Gallery](https://img.shields.io/badge/examples-88_scripts-06b6d4)](https://selectools.dev/examples/)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/johnnichev/selectools/blob/main/notebooks/getting_started.ipynb) [![Examples Gallery](https://img.shields.io/badge/examples-94_scripts-06b6d4)](https://selectools.dev/examples/)
 
 ```bash
 pip install selectools
@@ -130,7 +164,7 @@ Path("trace.html").write_text(trace_to_html(result.trace))
 - **Trace HTML viewer** — `trace_to_html(trace)` renders a standalone waterfall timeline
 - **Deprecation policy** — 2-minor-version window, programmatic introspection via `.__stability__`
 - **Security audit** — all 41 `# nosec` annotations reviewed and published in `docs/SECURITY.md`
-- **Quality infrastructure** — property-based tests (Hypothesis), thread-safety smoke suite, 5 new production simulations (4612 tests total)
+- **Quality infrastructure** — property-based tests (Hypothesis), thread-safety smoke suite, 5 new production simulations (5271 tests total)
 
 ### v0.19.1 — Advanced Agent Patterns
 
@@ -486,7 +520,7 @@ report.to_html("report.html")
 - **76 Examples**: Multi-agent graphs, RAG, hybrid search, streaming, structured output, traces, batch, policy, observer, guardrails, audit, sessions, entity memory, knowledge graph, eval framework, advanced agent patterns, stability markers, HTML trace viewer, and more
 - **Built-in Eval Framework**: 50 evaluators (30 deterministic + 21 LLM-as-judge), A/B testing, regression detection, HTML reports, JUnit XML, snapshot testing
 - **AgentObserver Protocol**: 45 lifecycle events with `run_id` correlation, `LoggingObserver`, `SimpleStepObserver`, OTel export
-- **5203 Tests**: Unit, integration, regression, and E2E with real API calls
+- **5271 Tests**: Unit, integration, regression, and E2E with real API calls
 
 ## Install
 
@@ -1110,7 +1144,7 @@ pytest tests/ -x -q          # All tests
 pytest tests/ -k "not e2e"   # Skip E2E (no API keys needed)
 ```
 
-5203 tests covering parsing, agent loop, providers, RAG pipeline, hybrid search, advanced chunking, dynamic tools, caching, streaming, guardrails, sessions, memory, eval framework, budget/cancellation, knowledge stores, orchestration, pipelines, agent patterns, stability markers, trace viewer, and E2E integration with real API calls.
+5271 tests covering parsing, agent loop, providers, RAG pipeline, hybrid search, advanced chunking, dynamic tools, caching, streaming, guardrails, sessions, memory, eval framework, budget/cancellation, knowledge stores, orchestration, pipelines, agent patterns, stability markers, trace viewer, and E2E integration with real API calls.
 
 ## License