PR #66652: feat(tools): add model_spawn tool — live session model switch and parallel ephemeral spawns

• Repository: openclaw/openclaw
• Author: perlowja
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/66652

Description (problem / solution / changelog)

Summary

• Adds model_spawn LLM-callable tool implementing the canonical spec in docs/tools/model-spawn.md
• live mode: switches the current session's model in-place (context preserved, takes effect at the next clean turn boundary via liveModelSwitchPending + session store)
• spawn single: delegates one task to a specified model in an ephemeral isolated session via spawnSubagentDirect
• spawn multi: fans out up to 10 tasks concurrently across different models via Promise.all — supports both model specialization (different subtasks to different models) and model comparison (same task across multiple models)
• Replaces the narrower model_switch tool (live-switch only, no spawn capability)
• Canonical spec (docs/tools/model-spawn.md) is language-agnostic; a conformant Rust implementation for zeroclaw is being submitted in parallel to zeroclaw-labs/zeroclaw

Files changed

Schema

{
  "mode": "live" | "spawn",
  "model": "provider/model-id",        // live or single spawn
  "task": "...",                        // single spawn or default for spawns[]
  "context": "...",                     // optional, prepended to task
  "spawns": [                           // multi-model parallel execution
    { "model": "...", "task": "...", "label": "...", "context": "..." }
  ],
  "cleanup": "delete" | "keep",        // default: "delete"
  "timeout_seconds": 120
}

Test plan

• live mode: verify liveModelSwitchPending is set in session store; next turn uses new model
• spawn single: task runs in isolated session on specified model; parent session model unchanged
• spawn multi: all entries run concurrently; results array contains one entry per spawn with label/index/model/status/output
• spawns[] fallback: per-entry omitted task inherits top-level task; per-entry omitted context inherits top-level context
• Mutual exclusion: providing both top-level model and spawns[] returns an error
• cleanup="keep": session persists after spawn completes

🤖 Generated with Claude Code

Changed files

• apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/tool-display.json (modified, +10/-0)
• docs/tools/model-spawn.md (added, +273/-0)
• src/agents/openclaw-tools.ts (modified, +13/-0)
• src/agents/tool-display-config.ts (modified, +5/-0)
• src/agents/tool-mutation.ts (modified, +1/-0)
• src/agents/tools/model-spawn-tool.test.ts (added, +379/-0)
• src/agents/tools/model-spawn-tool.ts (added, +319/-0)
• src/security/dangerous-tools.ts (modified, +2/-0)