Summary

The sessions_spawn tool description is too brief and lacks usage guidance, causing OpenClaw agents to consistently bypass sub-agent delegation and handle large/batch tasks directly in the main session.

Current behavior

The sessions_spawn tool description (in tool-catalog.ts) is:

"Spawn clean child session; default runtime="subagent". mode="run" one-shot background work. Subagents inherit parent workspace. Native subagents get task in first visible [Subagent Task] message. Native only: context="fork" only when child needs current transcript; else omit or isolated. Use for fresh child-session work."

This is purely a technical description of the tool mechanics. It does not tell the model when it should use sub-agents vs. doing work locally.

The problem

Agents consistently handle large tasks directly: reading many files, running batch exec commands, doing multi-step web searches — all in the main session. Even when AGENTS.md explicitly states "use sub-agents for tasks >10s or large file reads", agents ignore this rule because:

1. The sessions_spawn tool description itself gives no usage guidance
2. AGENTS.md rules are advisory text, not part of the tool definition
3. Models follow the path of least resistance: direct read/exec is their most natural tool-use pattern

Comparison: Codex

Codex (by OpenAI) solves this by embedding detailed usage guidance directly in the spawn_agent tool description:

• When to delegate: sidecar tasks that can run in parallel, concrete bounded subtasks
• When NOT to delegate: blocking work on the critical path, tightly coupled tasks
• After delegating: do meaningful non-overlapping work, don't wait by reflex
• Parallel patterns: split independent subtasks, run multiple agents in parallel

This guidance is part of the tool definition itself — the model sees it every time it considers calling the tool, not as a separate rules file.

Proposed solution

Enhance the sessions_spawn tool description to include usage guidance, similar to Codex's approach. Suggested additions:

### When to use sessions_spawn
- Large file reads or batch processing (>10s expected runtime)
- Multi-step web searches or data collection
- Tasks that can run independently in parallel with your local work
- Concrete, bounded subtasks with clear output

### When NOT to use sessions_spawn
- Quick lookups or single-file reads
- Tasks on the critical path that block your next immediate step
- Tightly coupled work that depends on current context

### After spawning
- Do meaningful non-overlapping local work while the sub-agent runs
- Results will be delivered when complete; no need to poll
- Do not redo delegated work yourself

Why this matters

Without usage guidance in the tool description, agents default to doing everything locally. This wastes tokens, increases latency, and defeats the purpose of having sub-agent capabilities. The tool description is the most effective place to influence model behavior because it's seen at decision time — unlike AGENTS.md which is background context.

Related issues

• Agent fails to execute rules despite knowing them - need forced rule checking mechanism #43295 (closed as plugin scope) — Agent fails to execute rules despite knowing them
• Agent repeatedly acts autonomously despite explicit rules in memory/context files #61237 (closed) — Agent repeatedly acts autonomously despite explicit rules
• [Feature]: edit tool description doesn't include an example, leading reasoning MoE models to mimic prior wrong shapes #90983 (closed, implemented via code fix) — edit tool description lacks example, causing model errors

Environment

• OpenClaw version: v2026.6.1
• Harness: native (non-Codex)
• Model: DeepSeek v4-flash (but observed across multiple model families)