Session log: Claude Code model selection Q&A + complexity-based sub-agent routing system

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/CLAUDE.md

@@ -102,6 +102,20 @@ You are NOT an executor. You coordinate specialized agents and preserve your con
 
 **DO NOT** query databases directly (no SSH/mysql/curl to API). **DO NOT** write production code. **DO NOT** run tests. **DO NOT** commit/push. Use the appropriate agent.
 
+### Model Routing (Complexity-Based)
+
+Before spawning an agent, pick a tier from `.claude/COMPLEXITY_ROUTING.md`:
+
+| Tier | Model | When |
+|------|-------|------|
+| 1 | `haiku` | Lookup, format, summarize, doc — no code changes |
+| 2 | (inherit) | Standard code, DB, tests, git — most work |
+| 3 | `opus` | Architecture, security, ambiguous failures, production risk |
+
+**Bump rule:** if the request involves `security`, `auth`, `credential`, `migration`, `production`, or `data loss` — bump one tier up.
+
+Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2 (inherits session model).
+
 ### Coordination Flow
 
 ```

.claude/COMPLEXITY_ROUTING.md

@@ -0,0 +1,74 @@
+# Complexity-Based Model Routing
+
+When spawning an agent, pick a tier based on the request signals below, then pass `model` accordingly.
+
+---
+
+## Tier 1 — Haiku (fast/cheap)
+
+**Signals:** single lookup, no code changes, classification, formatting, summarization, status check, documentation
+
+**Examples:**
+- "What's the status of X?"
+- Summarize or format a session log
+- Search/grep for a value
+- Convert or extract data
+- Write/update a markdown doc
+
+**Agents that default here:** documentation-squire, explore (quick searches), photo
+
+**Agent call:** `model: "haiku"`
+
+---
+
+## Tier 2 — Sonnet (default, inherit)
+
+**Signals:** standard code generation, routine DB queries, test execution, API work, multi-file reads, git operations
+
+**Examples:**
+- Add or modify an endpoint
+- Run tests and report results
+- Write a DB migration
+- Fetch credentials, configure a service
+- Commit and push changes
+
+**Agents that default here:** coding, database, testing, gitea, general-purpose, deep-explore (standard search)
+
+**Agent call:** omit `model` (inherits session model)
+
+---
+
+## Tier 3 — Opus (high-stakes reasoning)
+
+**Signals:** architectural decision, security/auth, 3+ interacting systems, ambiguous root cause, production data risk, anything that fails badly if wrong
+
+**Examples:**
+- Redesign an auth or data flow
+- Security or code review of a critical PR
+- Debug a multi-service race condition
+- Schema migration on production data
+- Evaluate competing architectural approaches
+
+**Agents that default here:** code-review (when Sequential Thinking triggers), deep-explore (architecture questions)
+
+**Agent call:** `model: "opus"`
+
+---
+
+## Bump Rule
+
+If the request contains ANY of these keywords, bump one tier up regardless of other signals:
+
+`security`, `auth`, `token`, `credential`, `migration`, `production`, `race condition`, `data loss`, `breach`, `encrypt`
+
+---
+
+## Quick Reference
+
+| Tier | Model | Typical cost | Use when |
+|------|-------|-------------|----------|
+| 1 | `haiku` | ~10x cheaper | Lookup, format, summarize, doc |
+| 2 | (inherit) | baseline | Standard code, DB, tests |
+| 3 | `opus` | ~5x more expensive | Architecture, security, ambiguous failures |
+
+Err toward Tier 2 when uncertain. Only use Opus when the reasoning stakes justify the cost.

session-logs/2026-04-18-session.md

@@ -176,3 +176,34 @@ No custom "Archived" status — used `Closed` for archival.
 4. **All items in WORKITEMS.md**
 5. **Cascades file search** — TickTick task for today
 6. **Review Dataforth engineering docs and send** — TickTick task for today
+
+---
+
+## Update: ~14:00
+
+### Topic: Claude Code model selection + complexity routing system
+
+#### What was discussed
+
+1. **Model selection in Claude Code** — confirmed it is always manual (no automatic complexity-based switching). Options: `/model`, `--model` flag, `ANTHROPIC_MODEL` env var, `settings.json`. The `opusplan` alias is the closest to automatic — uses Opus for planning phase, then switches to Sonnet for execution.
+
+2. **Sub-agent complexity detection** — confirmed we had NO complexity-based model routing for spawned agents. Existing behavior: rule-based routing by operation type, `>500 token` delegation threshold, a few hardcoded Haiku hints in `AGENT_QUICK_REFERENCE.md` for documentation-squire.
+
+#### What was built
+
+**New file: `.claude/COMPLEXITY_ROUTING.md`**
+
+Full 3-tier scoring rubric for sub-agent model selection:
+- Tier 1 (Haiku): lookup, format, summarize, doc — no code changes
+- Tier 2 (inherit/Sonnet): standard code, DB, tests, git — most work
+- Tier 3 (Opus): architecture, security, ambiguous failures, production risk
+
+Bump rule: if request contains `security`, `auth`, `token`, `credential`, `migration`, `production`, `race condition`, `data loss`, `breach`, `encrypt` → bump one tier up regardless.
+
+**Updated: `.claude/CLAUDE.md`**
+
+Inserted "Model Routing (Complexity-Based)" section in the coordinator block, just before Coordination Flow. Compact routing table + bump rule inline. References COMPLEXITY_ROUTING.md for full detail.
+
+#### Files modified
+- `.claude/COMPLEXITY_ROUTING.md` — new file, full rubric
+- `.claude/CLAUDE.md` — coordinator section updated with routing table