docs(model-routing): document per-agent model pins (#2431)

gitbooks/developing/architecture/agent-harness.md

@@ -159,7 +159,7 @@ Custom archetypes ship as TOML files under `$OPENHUMAN_WORKSPACE/agents/*.toml`
 When the orchestrator calls `spawn_subagent` (or one of the `delegate_*` convenience tools), the runner:
 
 1. Reads the parent's execution context from a task-local - the parent's provider, sandbox mode, cancellation fence, transcript root.
-2. Resolves the sub-agent's model - inherit from parent, follow a hint (`fast` / `reasoning` / `summarization`), or pin an exact model.
+2. Resolves the sub-agent's model - inline `model` override first, then config-level pins (`[orchestrator].model`, `[teams.*].lead_model`, `[teams.*].agent_model`), then the archetype hint or inherited parent model.
 3. Filters the parent's tool registry per the definition's `tools`, `disallowed_tools`, and `skill_filter`. In `fork` mode, the parent's full registry is inherited verbatim.
 4. Builds a narrow system prompt, omitting the sections the definition asks to strip.
 5. Runs an inner tool-call loop using the same machinery as the parent.

gitbooks/features/model-routing/README.md

@@ -52,6 +52,42 @@ Routing happens behind a single OpenHuman subscription. You don't hold separate
 - **Per call**. pass a concrete model name (no `hint:` prefix) and the router falls through to the default provider with that exact model.
 - **For a skill**. skills can pin a hint or a model in their manifest.
 
+## Per-agent model pins
+
+Sub-agents can also pin an exact model without disabling automatic routing for the rest of the app. Use this when an orchestrator or team lead needs a stronger model, while high-volume leaf agents should stay on a cheaper one.
+
+Inline calls win for one delegation:
+
+```json
+{
+  "agent_id": "researcher",
+  "model": "anthropic/claude-sonnet-4",
+  "prompt": "Collect source notes for the launch memo."
+}
+```
+
+Persistent defaults live in `config.toml`:
+
+```toml
+[orchestrator]
+model = "anthropic/claude-sonnet-4"
+
+[teams.research]
+lead_model = "openai/gpt-5.1"
+agent_model = "groq/llama-3.1-8b-instant"
+
+[teams.code]
+agent_model = "qwen/qwen3-coder"
+```
+
+Resolution order:
+
+1. Inline `model` on `spawn_subagent` or an archetype delegation call.
+2. `[orchestrator].model` or `[teams.<team>]` / built-in aliases such as `[teams.research]` and `[teams.code]`.
+3. The archetype's own model hint and the normal route table.
+
+For `[teams.*]`, `lead_model` applies to agents that can delegate and `agent_model` applies to leaf workers. If only one is set, the harness falls back to it for both roles.
+
 ## Why this isn't just "model switcher"
 
 Routing isn't a UI dropdown. The agent loop itself emits hints based on what it's about to do. You don't pick the model; the *task* does. That's the difference between "multi-model" and "smart routing".

gitbooks/features/native-tools/agent-coordination.md

@@ -21,6 +21,8 @@ Beyond doing the work, the agent has tools for *organising* the work - planning
 | `plan_exit`             | Exit a planning phase and start executing.                                                    |
 | `check_onboarding_status` / `complete_onboarding` | Gate behaviour on whether the user has finished onboarding.        |
 
+`spawn_subagent` and archetype delegation calls accept an optional `model` field for a one-off exact model pin. If it is omitted, the harness uses config-level per-agent pins when present and otherwise falls back to the normal model-routing hints.
+
 ## Why these are tools, not implicit behaviour
 
 Long tasks fall apart when the agent tries to keep everything in one head. Splitting work via TODOs and subagents means: