Add swarmModel field to per-agent settings and workerModel to spin config

[acreeger]

Fixes #735

Add swarmModel field to per-agent settings and workerModel to spin config

Problem

Configuring swarm-specific models for individual phase agents currently requires a verbose nested structure under agents.iloom-swarm-worker.agents:

{
  "agents": {
    "iloom-swarm-worker": {
      "model": "sonnet",
      "agents": {
        "iloom-issue-implementer": { "model": "sonnet" },
        "iloom-issue-complexity-evaluator": { "model": "haiku" }
      }
    }
  }
}

This is awkward because:

• The swarm-specific model for an agent lives far away from that agent's own config entry
• There's no way to look at `agents.iloom-issue-implementer` and know what model it uses in swarm mode
• The init wizard has to teach users about the nested structure rather than a simple per-agent field

Proposed Solution

1. Add `swarmModel` to `BaseAgentSettingsSchema`

Allow each agent to declare its own swarm-specific model directly:

```json
{
"agents": {
"iloom-issue-implementer": {
"model": "opus",
"swarmModel": "sonnet"
},
"iloom-issue-complexity-evaluator": {
"model": "haiku",
"swarmModel": "haiku"
}
}
}
```

This would insert into the fallback chain in `SwarmSetupService.ts` at a logical priority (e.g., between the existing `agents.iloom-swarm-worker.agents..model` and `agents.iloom-swarm-worker.model` steps):

1. `agents.iloom-swarm-worker.agents..model` — swarm-specific per-agent override (existing)
2. `agents..swarmModel` — per-agent swarm model (new)
3. `agents.iloom-swarm-worker.model` — blanket swarm worker model (existing)
4. Built-in swarm defaults (existing)
5. `agents..model` — base per-agent model (existing)
6. Agent definition file default (existing)

2. Add `workerModel` to `SpinAgentSettingsSchema`

The spin config controls the orchestrator, but there's no way to set the worker model from the spin config. A `workerModel` field would allow co-locating orchestrator and worker model config:

```json
{
"spin": {
"model": "sonnet",
"workerModel": "sonnet"
}
}
```

This is especially useful for presets, which need to configure both the orchestrator and worker together.

Impact

• Simplifies the init wizard — presets can reference clean per-agent `swarmModel` fields
• Makes swarm configuration more discoverable and self-documenting
• Backwards compatible — existing nested `agents.iloom-swarm-worker.agents` config still works at higher priority

---

This PR was created automatically by iloom.

[acreeger]

Complexity Assessment - Issue #735

Detailed Analysis Complete

Changes Required:

1. SettingsManager.ts (~30 LOC):

   • Add swarmModel field to BaseAgentSettingsSchema (lines 11-31)
   • Add workerModel field to SpinAgentSettingsSchema (lines 53-58)
   • Update schema descriptions to document new fallback chain
   • Add corresponding TypeScript type definitions for inferred types

2. SwarmSetupService.ts (~15 LOC):

   • Update fallback chain comment in renderSwarmAgents() to include new swarmModel field
   • Add line to extract swarmModel from per-agent settings before the loop (line 269)
   • Insert swarmModel check as Priority 1.5 in the fallback chain
   • Update renderSwarmWorkerAgent() to check workerModel field (line 357)

Complexity Evaluation

Metrics:

• Files affected: 2 (SettingsManager.ts, SwarmSetupService.ts)
• Estimated lines of code: ~45 new/modified LOC
• Breaking changes: No (fully backward compatible)
• Database migrations: No
• Cross-cutting changes: No (localized to settings + swarm setup)
• File architecture quality: Good (both files <1500 LOC, well-structured)

Key Observations:

1. Simplicity factors:

   • Pure schema extension (adding new optional fields)
   • Fallback chain is already well-established and documented
   • Changes are straightforward insertions into existing structures
   • No cascading impact to other systems
   • Comprehensive test file already exists (SwarmSetupService.test.ts)

2. Architectural clarity:

   • New fields follow existing patterns (optional enum fields)
   • Fallback chain logic is explicit and already documented
   • No architectural decisions needed - implementation follows directly from requirements
   • "How" is immediately obvious from "what"

3. Risk assessment:

   • Low risk: Pure additions, no deletions or breaking changes
   • Existing agents.iloom-swarm-worker.agents config continues to work
   • New fields have sensible defaults (use existing config if not specified)
   • All test patterns already established

Assumptions Table

Aspect	Assumption	Confidence
Scope	Only SettingsManager and SwarmSetupService need changes	High
Integration	No changes needed to init wizard or other commands	High
Testing	Existing test patterns sufficiently cover new fields	High
Defaults	workerModel not needed in SpinAgentSettingsSchema default value	High
Fallback priority	New swarmModel sits between explicit swarm config and base agent model	High

---

Complexity Assessment

Classification: SIMPLE

Metrics:

• Estimated files affected: 2
• Estimated lines of code: 45
• Breaking changes: No
• Database migrations: No
• Cross-cutting changes: No
• File architecture quality: Good
• Architectural signals triggered: None
• Overall risk level: Low

Reasoning: This is a straightforward schema extension with minimal logic changes. The fallback chain is already well-understood and documented, and both modified files are well-architected. No architectural decisions required - implementation follows directly from requirements with low integration risk.

[acreeger]

Combined Analysis & Plan - Issue #735

Executive Summary

Add a swarmModel field to both BaseAgentSettingsSchema (per-agent swarm model override) and SpinAgentSettingsSchema (spin config blanket worker model). This provides a cleaner, more discoverable way to configure swarm-specific models without requiring the verbose nested agents.iloom-swarm-worker.agents structure. The spin config swarmModel also enables presets to configure both orchestrator and worker models together. Per user correction, the field is named swarmModel (not workerModel) in both locations for naming consistency.

Questions and Key Decisions

Question	Answer (Assumed)
Should spin.swarmModel participate in the phase agent fallback chain or only affect the worker agent's own frontmatter model?	Both -- it should be the lowest-priority blanket override for phase agents (below agents.iloom-swarm-worker.model) AND a fallback for the worker agent's frontmatter model. This maximizes the utility of the spin config as a single place to set the worker model.
What is the priority of agents.<name>.swarmModel relative to spin.swarmModel?	Per-agent swarmModel (Priority 1.5) should beat spin.swarmModel (Priority 2.5, new) since per-agent config is more specific. Full chain: P1: swarm-worker.agents override > P1.5: per-agent swarmModel > P2: swarm-worker.model > P2.5: spin.swarmModel > P3: built-in swarm defaults > P4: base agent model > P5: .md default
Should spin.swarmModel also affect the worker agent's own frontmatter model (line 357 of SwarmSetupService.ts)?	Yes -- the fallback for the worker agent frontmatter should be: agents.iloom-swarm-worker.model > spin.swarmModel > default 'sonnet'

Implementation Overview

High-Level Execution Phases

1. Schema Updates: Add swarmModel to BaseAgentSettingsSchema, SpinAgentSettingsSchema, and their NoDefaults variants
2. Fallback Chain Updates: Insert new priorities into renderSwarmAgents() and renderSwarmWorkerAgent() in SwarmSetupService.ts
3. Tests: Add tests for both new fallback priorities in SwarmSetupService.test.ts and schema validation in SettingsManager.test.ts
4. Documentation: Update fallback chain docs and add swarmModel examples in iloom-commands.md

Quick Stats

• 4 files to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis & Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: Swarm-specific model config requires verbose nested structure; no per-agent swarmModel field exists, and spin config cannot set the worker model.
• Architectural context: Two schemas (BaseAgentSettingsSchema, SpinAgentSettingsSchema) define the config structure; SwarmSetupService.renderSwarmAgents() implements the fallback chain for phase agents; renderSwarmWorkerAgent() determines the worker agent's model.
• Edge cases: spin.swarmModel should not override a more-specific agents.<name>.swarmModel; when swarmModel is not set, fallback behavior must remain identical to current behavior.

Codebase Research

• Entry point: SettingsManager.ts:11-31 (BaseAgentSettingsSchema), SettingsManager.ts:53-58 (SpinAgentSettingsSchema)
• Fallback chain: SwarmSetupService.ts:249-281 (renderSwarmAgents), SwarmSetupService.ts:357 (renderSwarmWorkerAgent worker model)
• SpinAgentSettingsSchema NoDefaults variant: SettingsManager.ts:593-598
• Similar patterns: Existing fields (model, enabled, providers, review) on BaseAgentSettingsSchema follow the same optional enum pattern
• Tests: SwarmSetupService.test.ts has comprehensive tests for the fallback chain; SettingsManager.test.ts:2821-2851 tests getSpinModel

Affected Files

• /src/lib/SettingsManager.ts:11-31,53-58,593-598 - Schema definitions for BaseAgent, SpinAgent, and NoDefaults variant
• /src/lib/SwarmSetupService.ts:249-281,357 - Fallback chain logic and worker model resolution
• /src/lib/SwarmSetupService.test.ts - Tests for swarm model override fallback chain
• /docs/iloom-commands.md:1614-1676 - Swarm model configuration documentation

Integration Points

• BaseAgentSettingsSchema is used by AgentSettingsSchema (extends it) and by IloomSettingsSchema.agents record
• SpinAgentSettingsSchema is used by IloomSettingsSchema.spin and IloomSettingsSchemaNoDefaults.spin
• renderSwarmAgents() reads settings via this.settingsManager.loadSettings() and accesses settings.agents
• renderSwarmWorkerAgent() also reads settings and accesses settings.agents['iloom-swarm-worker']?.model and settings.spin?.swarmModel (new)

Medium Severity Risks

• Fallback chain ordering: Must ensure spin.swarmModel sits below agents.iloom-swarm-worker.model to avoid surprising overrides; verified by test.

---

Implementation Plan

Automated Test Cases to Create

Test File: /src/lib/SwarmSetupService.test.ts (MODIFY)

Click to expand test structure (15 lines)

// In describe('swarm-specific model overrides'):
it('uses per-agent swarmModel when configured', /* ... */)
it('per-agent swarmModel beats blanket swarm worker model', /* ... */)
it('per-agent swarmModel beats spin.swarmModel', /* ... */)
it('spin.swarmModel acts as blanket override when no swarm-worker.model set', /* ... */)
it('agents.iloom-swarm-worker.model beats spin.swarmModel', /* ... */)

// In describe('renderSwarmWorkerAgent'):
it('uses spin.swarmModel for worker frontmatter when agents.iloom-swarm-worker.model not set', /* ... */)
it('agents.iloom-swarm-worker.model beats spin.swarmModel for worker frontmatter', /* ... */)

Test File: /src/lib/SettingsManager.test.ts (MODIFY)

// Schema validation tests for swarmModel on BaseAgentSettingsSchema and SpinAgentSettingsSchema
it('accepts swarmModel on agent settings', /* ... */)
it('accepts swarmModel on spin settings', /* ... */)

Files to Modify

1. /src/lib/SettingsManager.ts:11-31

Change: Add swarmModel optional enum field to BaseAgentSettingsSchema after the model field.

// Add after line 15 (after model field):
swarmModel: z
    .enum(['sonnet', 'opus', 'haiku'])
    .optional()
    .describe('Model to use for this agent in swarm mode. Overrides the base model when running inside swarm workers.'),

2. /src/lib/SettingsManager.ts:53-58

Change: Add swarmModel optional enum field to SpinAgentSettingsSchema after the model field.

// Add after line 57 (after model field):
swarmModel: z
    .enum(['sonnet', 'opus', 'haiku'])
    .optional()
    .describe('Model for swarm worker agents. Sets the default model for all phase agents in swarm mode when not overridden by per-agent settings.'),

3. /src/lib/SettingsManager.ts:593-598

Change: Add swarmModel to the SpinAgentSettingsSchema NoDefaults variant (inside IloomSettingsSchemaNoDefaults.spin).

// Add after line 595:
swarmModel: z.enum(['sonnet', 'opus', 'haiku']).optional(),

4. /src/lib/SwarmSetupService.ts:249-281

Change: Update the fallback chain comment and logic in renderSwarmAgents() to include per-agent swarmModel (Priority 1.5) and spin.swarmModel (Priority 2.5).

The updated fallback chain:

// Priority 1: agents.iloom-swarm-worker.agents.<agent-name>.model (swarm-specific per-agent)
// Priority 1.5: agents.<agent-name>.swarmModel (per-agent swarm model, NEW)
// Priority 2: agents.iloom-swarm-worker.model (blanket swarm worker model)
// Priority 2.5: spin.swarmModel (spin config blanket swarm model, NEW)
// Priority 3: built-in swarm defaults (e.g., implementer defaults to sonnet)
// Priority 4: agents.<agent-name>.model (base per-agent, already applied by loadAgents)
// Priority 5: agent .md file default (already applied by loadAgents)

Implementation: After extracting swarmWorkerModel (line 261), also extract:

• const spinSwarmModel = settings?.spin?.swarmModel (from spin config)
• Inside the loop, read const perAgentSwarmModel = settings?.agents?.[agentName]?.swarmModel for each agent
• Insert checks between existing priority 1 and priority 2 (for per-agent swarmModel), and between priority 2 and built-in defaults (for spin.swarmModel)

5. /src/lib/SwarmSetupService.ts:357

Change: Update worker agent frontmatter model resolution to include spin.swarmModel as fallback.

// Change from:
const workerModel = settings?.agents?.['iloom-swarm-worker']?.model ?? 'sonnet'
// To:
const workerModel = settings?.agents?.['iloom-swarm-worker']?.model ?? settings?.spin?.swarmModel ?? 'sonnet'

6. /docs/iloom-commands.md:1614-1676

Change: Update the Worker Model Configuration section, Phase Agent Model Overrides section, and Fallback chain table to document swarmModel on both per-agent and spin config, plus the new fallback priorities.

Detailed Execution Order

NOTE: These steps are executed in a SINGLE implementation run. The implementer follows them sequentially.

1. Schema Updates (SettingsManager.ts)

   • Files: /src/lib/SettingsManager.ts
   • Add swarmModel to BaseAgentSettingsSchema after line 15 -> Verify: builds successfully
   • Add swarmModel to SpinAgentSettingsSchema after line 57 -> Verify: builds successfully
   • Add swarmModel to IloomSettingsSchemaNoDefaults.spin after line 595 -> Verify: builds successfully

2. Fallback Chain Updates (SwarmSetupService.ts)

   • Files: /src/lib/SwarmSetupService.ts
   • Update fallback chain comments (lines 249-254) -> Verify: accurate
   • Extract spinSwarmModel from settings?.spin?.swarmModel near line 261 -> Verify: compiles
   • Insert per-agent swarmModel check in loop (new priority 1.5 between lines 270-273) -> Verify: correct ordering
   • Insert spin.swarmModel check in loop (new priority 2.5 between lines 273-276) -> Verify: correct ordering
   • Update worker model resolution at line 357 to include spin.swarmModel fallback -> Verify: compiles

3. Tests (SwarmSetupService.test.ts, SettingsManager.test.ts)

   • Files: /src/lib/SwarmSetupService.test.ts, /src/lib/SettingsManager.test.ts
   • Add ~7 new test cases following existing patterns -> Verify: pnpm test passes

4. Documentation (iloom-commands.md)

   • Files: /docs/iloom-commands.md
   • Update fallback chain list (lines 1649-1654) with new priorities -> Verify: accurate
   • Add swarmModel examples to Worker Model Configuration and Phase Agent sections -> Verify: examples are correct
   • Add spin.swarmModel documentation -> Verify: complete

5. Build Verification

   • Run pnpm build -> Verify: no compilation errors
   • Run pnpm test -> Verify: all tests pass

Dependencies and Configuration

None

---

• Perform lightweight codebase research
• Check for duplication opportunities
• Create implementation plan
• Post final analysis and plan

[acreeger]

Implementation Complete

Summary

Added swarmModel field to both BaseAgentSettingsSchema (per-agent swarm model override) and SpinAgentSettingsSchema (spin config blanket swarm model). Extended the fallback chain with two new priority levels and updated all documentation.

Changes Made

• src/lib/SettingsManager.ts: Added swarmModel optional enum field to BaseAgentSettingsSchema, SpinAgentSettingsSchema, and IloomSettingsSchemaNoDefaults
• src/lib/SwarmSetupService.ts: Extended fallback chain with per-agent swarmModel (priority 2) and spin.swarmModel (priority 4); updated worker agent frontmatter model resolution
• src/lib/SwarmSetupService.test.ts: Added 8 new tests covering all fallback priority combinations
• src/lib/SettingsManager.test.ts: Added 5 schema validation tests for swarmModel
• docs/iloom-commands.md: Updated fallback chain docs, examples, and configuration reference

Validation Results

• Tests: 4327 passed (126 test files)
• Build: Passed
• Lint: Passed

---

Detailed Changes by File (click to expand)

src/lib/SettingsManager.ts

Changes: Schema extensions

• Added swarmModel optional enum field (sonnet/opus/haiku) to BaseAgentSettingsSchema
• Added swarmModel optional enum field to SpinAgentSettingsSchema with description clarifying it's overridden by per-agent swarm-specific settings
• Added swarmModel to IloomSettingsSchemaNoDefaults.spin variant

src/lib/SwarmSetupService.ts

Changes: Fallback chain extension

• Updated priority numbering to clean 1-7 scheme (aligned with docs)
• Added extraction of spinSwarmModel from settings?.spin?.swarmModel
• Added extraction of perAgentSwarmModel from settings?.agents?.[agentName]?.swarmModel in the agent loop
• Inserted priority 2 (per-agent swarmModel) and priority 4 (spin.swarmModel) into the if/else-if chain
• Updated renderSwarmWorkerAgent() to fall back to spin.swarmModel before default 'sonnet'

src/lib/SwarmSetupService.test.ts

Changes: 8 new test cases

• swarm-specific per-agent override beats per-agent swarmModel (P1 > P2)
• uses per-agent swarmModel when configured (P2 standalone)
• per-agent swarmModel beats blanket swarm worker model (P2 > P3)
• per-agent swarmModel beats spin.swarmModel (P2 > P4)
• spin.swarmModel acts as blanket override when no swarm-worker.model set (P4 standalone)
• agents.iloom-swarm-worker.model beats spin.swarmModel (P3 > P4)
• uses spin.swarmModel for worker frontmatter when agents.iloom-swarm-worker.model not set
• agents.iloom-swarm-worker.model beats spin.swarmModel for worker frontmatter

src/lib/SettingsManager.test.ts

Changes: 5 schema validation tests

• Validates swarmModel acceptance on BaseAgentSettingsSchema
• Validates all valid model enum values
• Validates rejection of invalid values
• Validates swarmModel acceptance on SpinAgentSettingsSchema
• Validates all valid model enum values on SpinAgentSettingsSchema

docs/iloom-commands.md

Changes: Documentation updates

• Updated fallback chain to 7 priorities (from 5) with new P2 and P4
• Added swarmModel examples in per-agent and spin config sections
• Updated Important/Note callouts with correct priority numbers

[acreeger]

Implementation Complete - Issue #735 ✅

Summary

Added swarmModel field to BaseAgentSettingsSchema (per-agent swarm model override) and SpinAgentSettingsSchema (spin config blanket worker model). Updated the fallback chain in SwarmSetupService.ts to include two new priorities: per-agent swarmModel (priority 1.5) and spin.swarmModel (priority 2.5). Also updated renderSwarmWorkerAgent to use spin.swarmModel as a fallback for the worker agent's frontmatter model.

Changes Made

• src/lib/SettingsManager.ts: Added swarmModel field to BaseAgentSettingsSchema, SpinAgentSettingsSchema, and IloomSettingsSchemaNoDefaults.spin
• src/lib/SwarmSetupService.ts: Extended fallback chain with per-agent swarmModel (P1.5) and spin.swarmModel (P2.5); updated worker frontmatter model resolution
• src/lib/SwarmSetupService.test.ts: Added 7 new tests covering the new fallback priorities
• src/lib/SettingsManager.test.ts: Added 5 schema validation tests for swarmModel on both schemas
• docs/iloom-commands.md: Updated fallback chain documentation, added swarmModel examples for both per-agent and spin config

Validation Results

• ✅ Build: Passed
• ✅ Tests: 4326 passed / 4349 total (23 skipped)
• ✅ Lint: Passed (0 warnings)

---

📋 Detailed Changes by File (click to expand)

Files Modified

src/lib/SettingsManager.ts

Changes: Added swarmModel optional enum field (sonnet | opus | haiku) to three locations:

• BaseAgentSettingsSchema (after model field) - enables per-agent swarm model config
• SpinAgentSettingsSchema (after model field) - enables spin config blanket worker model
• IloomSettingsSchemaNoDefaults.spin object - the no-defaults variant for settings merging

src/lib/SwarmSetupService.ts

Changes: Updated renderSwarmAgents() fallback chain and renderSwarmWorkerAgent() model resolution.

• Fallback chain now: P1 swarm-worker.agents override > P1.5 per-agent swarmModel > P2 swarm-worker.model > P2.5 spin.swarmModel > P3 built-in defaults > P4/P5 base model
• Worker frontmatter: agents.iloom-swarm-worker.model ?? settings.spin.swarmModel ?? 'sonnet'

src/lib/SwarmSetupService.test.ts

Changes: Added 7 new tests in two sections:

• 5 tests in swarm-specific model overrides: per-agent swarmModel usage, priority over blanket/spin, spin.swarmModel as blanket, swarm-worker.model beating spin.swarmModel
• 2 tests in renderSwarmWorkerAgent: spin.swarmModel for worker frontmatter, swarm-worker.model priority over spin.swarmModel

src/lib/SettingsManager.test.ts

Changes: Added 5 schema validation tests in new swarmModel schema validation describe block:

• Validates swarmModel acceptance on BaseAgentSettingsSchema and SpinAgentSettingsSchema
• Tests all valid model values and rejects invalid ones
• Tests combined model + swarmModel on SpinAgentSettingsSchema

docs/iloom-commands.md

Changes: Updated Worker Model Configuration and Phase Agent Model Overrides sections:

• Added spin.swarmModel documentation with example
• Added per-agent swarmModel documentation with example
• Updated fallback chain from 4 to 7 steps
• Updated resolution table references
• Added new --set flag examples

Dependencies Added

None

[acreeger]

iloom Session Summary

Key Themes:

• The swarm architecture has three distinct model layers (spin orchestrator, swarm worker, phase agents) that are completely independent — conflating them causes significant confusion.
• The old agents.iloom-swarm-worker.agents.<name>.model nested override pattern was dead complexity — agents.<name>.swarmModel replaces it cleanly.
• spin.swarmModel controls the spin orchestrator's model specifically in swarm mode; it has no effect on workers or phase agents.

---

Session Details (click to expand)

Key Insights

• Three separate model layers, no interaction between them:

  • spin.model / spin.swarmModel → the spin orchestrator agent only
  • agents.iloom-swarm-worker.model → the worker agent that handles each child issue only
  • agents.<name>.swarmModel / agents.<name>.model → phase agents (implementer, planner, analyzer, etc.) only
  • None of these bleed into each other. The old fallback chain was wrong to mix them.

• spin.swarmModel is not a "convenience" shorthand — it serves a distinct purpose: allowing the spin orchestrator to use a different model when it's supervising a swarm versus when it's running a single issue/PR/branch workflow. getSpinModel(settings, 'swarm') resolves it.

• The old hardcoded { 'iloom-issue-implementer': 'sonnet' } default was inappropriate — it silently overrode a user's explicit agents.iloom-issue-implementer.model unless they also set an explicit swarm override. Removing it means the agent's .md file is the right place for any default.

• AgentSettingsSchema retains a agents sub-record field for nested config (used for subAgentTimeout under iloom-swarm-worker). The old .describe() on this field falsely advertised it as the mechanism for swarm model overrides — it no longer is.

Decisions Made

• swarmModel naming over workerModel for the spin config field — keeps naming consistent since the same field name means "my model in swarm mode" regardless of which agent it appears on.

• Removed agents.iloom-swarm-worker.agents.<name>.model from the resolution chain entirely — it was the original mechanism for per-phase-agent swarm overrides, but agents.<name>.swarmModel does the same thing with far less nesting and is more discoverable.

• agents.iloom-swarm-worker.model does NOT affect phase agents — contrary to what the old code did (using it as a blanket override for all phase agents), it only controls the worker agent's own frontmatter model. Phase agents are independent.

• Phase agent model resolution simplified to two rules:

  1. If agents.<name>.swarmModel is set → use it
  2. Otherwise → keep whatever loadAgents() already resolved (base model or .md default)

Challenges Resolved

• Architecture was initially misunderstood — early implementation had spin.swarmModel participating in the phase agent fallback chain AND as a fallback for the worker agent model. The user clarified these are three independent layers, which eliminated both of those usages.

• Stale schema descriptions — after removing the nested agents.iloom-swarm-worker.agents override mechanism from the code, the Zod .describe() strings on AgentSettingsSchema.agents and the IloomSettingsSchema agents record still advertised it as a valid pattern. Users configuring it would get silent no-ops.

Lessons Learned

• When adding model configuration to a multi-agent system, identify which agent layer each setting belongs to before writing any code. The spin/worker/phase distinction is the load-bearing architecture here.

• Hardcoded per-agent defaults in the override resolution logic are a footgun — they silently win over explicit user config unless carefully ordered. Defaults belong in agent definition files, not in resolution logic.

• loadAgents() in AgentManager returns a fresh object per call — mutation of the returned agents dict in renderSwarmAgents is safe. This is non-obvious from the call site.

---

Generated with 🤖❤️ by iloom.ai