README: Intelligence Routing — Phase 8 dev journey + features + troubleshooting

README.md

@@ -33,6 +33,7 @@
   <img src="https://img.shields.io/badge/Streaming_SSE-✓-success" />
   <img src="https://img.shields.io/badge/Tool_Calls-✓-success" />
   <img src="https://img.shields.io/badge/AI_Assist-✓-success" />
+  <img src="https://img.shields.io/badge/Intelligence_Routing-✓-success" />
   <img src="https://img.shields.io/badge/Self_Revive_Watchdog-✓-success" />
 </p>
 
@@ -130,6 +131,19 @@ A three-component system:
 - **ErrorAnalyzer** — learns from 4xx errors, retries with adjusted parameters (max 2 retries)
 - **Schema cache** with 24h staleness TTL for provider capabilities
 
+### Intelligence Routing (v3.7.0)
+- **Three-layer self-healing system** — the agent loop never stalls, even when the model speaks gibberish
+- **Layer 1 — Deep URL Extraction**: When `<explore_agent>` hides URLs inside nested JSON (`messages: [{"content": "https://..."}]`), the parser drills into the JSON structure to find them. Module-level `_build_explore_cmd()` is reused across parser + stream path.
+- **Layer 2 — Escalation Auto-Proceed**: `<require_escalation>` and `<request_escalation_permission>` blocks are detected and auto-resolved — the model doesn't get stuck waiting for permissions that don't exist.
+- **Layer 3 — Intent-Based Command Synthesis**: When ALL parsers fail, 5 heuristics analyze the model's plain-text output and synthesize a working command:
+  1. URL detected → `curl` it
+  2. File path mentioned → `cat` or `ls` it
+  3. Shell command in quotes → extract and run it
+  4. "explore"/"fetch" intent → use the last URL the user mentioned
+  5. "I need to"/"let me" intent → echo a diagnostic so the loop continues
+- **Session URL memory** — `_last_user_urls` deque (20 entries) tracks URLs from user messages across the session, giving the synthesizer context to work with
+- **54 self-test patterns** — comprehensive coverage of all three layers
+
 ### GTK Launcher (`codex-launcher-gui`)
 - **Endpoint manager** — add, edit, delete, set default providers
 - **Provider presets** — one-click setup for 15+ providers with pre-filled URLs and model lists
@@ -324,6 +338,83 @@ Built a cascading parser chain (`DSML → bash → explore → tool_call → XML
 
 **Verification:** `--self-test` flag runs 19 automated tests covering all edge cases. Debug logging to `~/.cache/codex-proxy/cc-debug.log` captures every parser decision for troubleshooting.
 
+### Phase 8: Intelligence Routing — When the Model Refuses to Speak Machine
+
+**Problem:** The 17-fix parser chain from Phase 7 was powerful — it could handle DSML, XML, JSON, bash blocks, explore tags, you name it. But there was one edge case it couldn't crack: **when the model doesn't produce a parseable tool-call format at all**.
+
+In production, `deepseek/deepseek-v4-flash` via Command Code kept doing things like:
+
+```
+<explore_agent>
+messages: [{"content": "Understand the Z.AI-Chat-for-Android repo at https://..."}]
+</explore_agent>
+```
+
+or:
+
+```
+<require_escalation>
+I need elevated permissions to access the repository.
+</require_escalation>
+```
+
+or just plain English: *"I need to fetch the README from the repository to understand the app structure."*
+
+In every case, `parsed_tool_calls=0`. No tool to execute. The Codex agent loop ground to a halt. The user saw "thinking..." forever.
+
+**The insight:** The model is trying to communicate *intent*, just not in a format we can parse. Instead of adding more regex patterns, what if we could **read the model's mind** — understand what it *wants* to do, and synthesize the command for it?
+
+**Intelligence Routing — Three Layers of Escalation:**
+
+```
+Layer 1: "Fix the input"     — Can we extract more from what the model gave us?
+Layer 2: "Handle the intent" — Is the model asking for something we can auto-resolve?
+Layer 3: "Read the mind"     — What is the model trying to do? Just do it for it.
+```
+
+**Layer 1 — Deep URL Extraction (FIX 23):**
+
+The `<explore_agent>` handler had a URL regex, but the URL was trapped inside `{"content": "https://..."}` — the trailing `"` broke matching. The fix: after the initial regex fails, `json.loads()` the entire block, walk the JSON tree, and pull URLs out of `content` fields. The `_build_explore_cmd()` function was extracted to module level so both the parser and the stream handler could use it.
+
+```python
+# Before: regex fails, URL lost
+# After: json.loads -> iterate items -> extract content -> find URL
+```
+
+**Layer 2 — Escalation Auto-Proceed (FIX 24):**
+
+`<require_escalation>` blocks are the model's way of saying "I need more permissions." The CC adapter doesn't have an escalation mechanism — these blocks were silently dropped. The fix: detect them (both closed `<tag>...</tag>` and bare `<tag />` forms), extract any URL inside them, and auto-proceed with an explore command or a diagnostic echo.
+
+```python
+# Model: <require_escalation>Please let me run curl</require_escalation>
+# Proxy: Okay, here's your curl command → exec_command synthesized
+```
+
+**Layer 3 — Intent-Based Command Synthesis (FIX 25):**
+
+The crown jewel. When ALL parsers return empty — no DSML, no XML, no JSON, no fallback regex matches — the system doesn't give up. It analyzes the model's raw text through **5 heuristic lenses** in priority order:
+
+| Priority | Signal | Synthesized Command |
+|:--------:|--------|---------------------|
+| 1 | URL in text | `curl` to fetch it |
+| 2 | File path reference | `cat` or `ls` the file |
+| 3 | Shell command in backticks/quotes | Extract and run it |
+| 4 | "explore"/"fetch" + last user URL | Full explore command |
+| 5 | "I need to"/"let me" intent | Echo diagnostic |
+
+The system also maintains a **session URL memory** (`_last_user_urls`, a deque of the last 20 URLs from user messages) so heuristic 4 always has a URL to work with, even when the model's text doesn't contain one.
+
+```python
+# Model: "I should explore the repository to understand its structure."
+# Parser: empty (no parseable format)
+# Layer 3 heuristic 4: "explore" detected, pulling URL from session memory...
+# Result: exec_command with full curl pipeline
+```
+
+**The result:** Before Intelligence Routing, `parsed_tool_calls=0` meant **game over** — the agent loop stalled permanently. After Intelligence Routing, `parsed_tool_calls=0` triggers the self-healing chain and the loop **always** gets a tool call to execute. The model can speak in tongues and the system still works.
+
+**Test coverage:** 54 self-test patterns (up from 41), with 13 new tests specifically for Intelligence Routing layers.
+
 ---
 
 ## Architecture Deep Dive
@@ -454,6 +545,9 @@ README.md                         # This file
 | CC tool calls have wrong args | Double-wrapped arguments | V3.5 three-tier parser + recursive unwrapping |
 | Proxy crashes mid-session | Unhandled streaming error | V3.5 self-revive watchdog auto-restarts |
 | CC 403 upgrade_required | Missing version header | V3.5 always sends `x-command-code-version` |
+| CC explore_agent can't find URL | URL hidden inside JSON messages | V3.7 Layer 1 drills into JSON to extract URLs |
+| CC agent stalls on escalation blocks | `<require_escalation>` not handled | V3.7 Layer 2 auto-proceeds past escalation requests |
+| CC agent stalls — no tool calls at all | Model output format unrecognized | V3.7 Layer 3 synthesizes command from text intent |
 
 ---