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

[aqilaziz]

Summary

• Documents inline model overrides for spawn_subagent / archetype delegation.
• Adds config.toml examples for [orchestrator].model and [teams.*] lead_model / ^Ggent_model pins.
• Updates the agent harness architecture docs with the current model-resolution precedence.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy - N/A: docs-only change.
• Diff coverage >= 80% - N/A: docs-only change.
• Coverage matrix updated - N/A: docs-only change.
• All affected feature IDs from the matrix are listed in the PR description under ## Related - N/A.
• No new external network dependencies introduced.
• Manual smoke checklist updated if this touches release-cut surfaces - N/A.
• Linked issue closed via Closes #NNN in the ## Related section.

Validation

• git diff --check

Related

• Closes Feature Request : Per-agent LLM model pinning in spawn_subagent and archetype_delegation #1837

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: codex/1837-model-pin-docs
• Commit SHA: $sha

Validation Run

• git diff --check

Behavior Changes

• No runtime behavior change. Documents existing per-agent model pin support.

Parity Contract

• Existing automatic model routing behavior remains unchanged.
• Per-agent model pins stay optional; omitted pins keep using route hints and defaults.

Duplicate / Superseded PR Handling

• Duplicate PR(s): none found for Feature Request : Per-agent LLM model pinning in spawn_subagent and archetype_delegation #1837.
• Canonical PR: this PR.
• Resolution: N/A.

Summary by CodeRabbit

• Documentation
  • Refined priority order for resolving a sub-agent’s model: inline delegation override → config-level per-agent pins → archetype hint or inherited model.
  • Added a “per-agent model pins” section with JSON and TOML examples and role-mapping guidance for lead vs. worker models.
  • Clarified optional model field in agent delegation/spawn calls and documented fallback routing behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 9b093bf4-2a53-4988-871a-ef7e8d9c0f7e

📥 Commits

Reviewing files that changed from the base of the PR and between 8da5a76 and 184a5ae.

📒 Files selected for processing (1)

• gitbooks/features/model-routing/README.md

✅ Files skipped from review due to trivial changes (1)

• gitbooks/features/model-routing/README.md

---

📝 Walkthrough

Walkthrough

This PR updates documentation to explain per-agent LLM model pinning for multi-agent swarms. It documents the resolution order for sub-agent models (inline override → config-level pins → archetype/inherited), configuration syntax examples, and optional model field usage in API calls.

Changes

Model pinning feature documentation

Layer / File(s)	Summary
Model resolution hierarchy documentation gitbooks/developing/architecture/agent-harness.md, gitbooks/features/model-routing/README.md	Documents the priority order for sub-agent model resolution: inline model parameter overrides config-level per-agent pins (model, lead_model, agent_model), which override archetype hints or inherited parent model. Includes config.toml examples for orchestrator and team-level defaults, plus role mapping rules for lead_model (delegating agents) vs agent_model (leaf workers).
API documentation for model pinning gitbooks/features/native-tools/agent-coordination.md	Documents that spawn_subagent and archetype_delegation accept an optional model field for one-off model pinning; when omitted, the harness falls back to config-level per-agent pins or automatic routing.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• tinyhumansai/openhuman#1896: Implements the inline model override fast-path used during sub-agent provider resolution; this PR documents that behavior.
• tinyhumansai/openhuman#1905: Implements config-level per-agent pins used during session/sub-agent model resolution; this PR documents the resulting precedence.

Suggested reviewers

• senamakel

Poem

🐰 A little rabbit hops through docs with glee,
Pinning models so each agent runs free.
Inline says first, then config answers the call,
Archetype whispers if no one pins at all.
Hooray for swarms that know their role and be!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: documenting per-agent model pins in the model-routing feature area.
Linked Issues check	✅ Passed	The PR documents all core requirements from issue #1837: inline model parameter for spawn_subagent and archetype_delegation, config-level per-team/orchestrator model pins, resolution precedence, and fallback behavior.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to documenting per-agent model pins as specified in issue #1837; no unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@gitbooks/features/model-routing/README.md`:
- Line 86: The resolution rule text uses inconsistent key wording: replace the
instance of "[teams.<agent_id>]" in the model-routing README with a team-scoped
key such as "[teams.<team>]" (or add an explicit note explaining that
"<agent_id>" maps to a team identifier) so examples and explanations
consistently use the team key; update the sentence that lists
"[orchestrator].model or [teams.<agent_id>] / built-in aliases..." to use
"[teams.<team>]" (or add a parenthetical mapping) and ensure any surrounding
examples or references elsewhere in the same section use the same
"[teams.<team>]" token.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a9dfa21d-3d51-41ab-b741-b9752cf03b0f

📥 Commits

Reviewing files that changed from the base of the PR and between bf6f25e and 8da5a76.

📒 Files selected for processing (3)

• gitbooks/developing/architecture/agent-harness.md
• gitbooks/features/model-routing/README.md
• gitbooks/features/native-tools/agent-coordination.md